helloloop 0.1.0

package/src/cli.mjs

@@ -0,0 +1,262 @@
+import path from "node:path";
+import { spawnSync } from "node:child_process";
+
+import { createContext } from "./context.mjs";
+import { fileExists } from "./common.mjs";
+import { scaffoldIfMissing } from "./config.mjs";
+import { installPluginBundle } from "./install.mjs";
+import { runLoop, runOnce, renderStatusText } from "./runner.mjs";
+
+function parseArgs(argv) {
+  const [command = "status", ...rest] = argv;
+  const options = {
+    requiredDocs: [],
+    constraints: [],
+  };
+
+  for (let index = 0; index < rest.length; index += 1) {
+    const arg = rest[index];
+    if (arg === "--dry-run") options.dryRun = true;
+    else if (arg === "--allow-high-risk") options.allowHighRisk = true;
+    else if (arg === "--force") options.force = true;
+    else if (arg === "--task-id") { options.taskId = rest[index + 1]; index += 1; }
+    else if (arg === "--max-tasks") { options.maxTasks = Number(rest[index + 1]); index += 1; }
+    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 === "--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 {
+      throw new Error(`未知参数：${arg}`);
+    }
+  }
+
+  return { command, options };
+}
+
+function helpText() {
+  return [
+    "用法：helloloop <command> [options]",
+    "",
+    "命令：",
+    "  install               安装插件到 Codex Home（适合 npx / npm bin 分发）",
+    "  init                  初始化 .helloloop 配置",
+    "  status                查看 backlog 与下一任务",
+    "  next                  生成下一任务干跑预览",
+    "  run-once              执行一个任务",
+    "  run-loop              连续执行多个任务",
+    "  doctor                检查 Codex、当前插件 bundle 与目标仓库 .helloloop 配置是否可用",
+    "",
+    "选项：",
+    "  --codex-home <dir>    Codex Home，install 默认使用 ~/.codex",
+    "  --repo <dir>          目标仓库根目录，默认当前目录",
+    "  --config-dir <dir>    配置目录，默认 .helloloop",
+    "  --dry-run             只生成提示与预览，不真正调用 codex",
+    "  --task-id <id>        指定任务 id",
+    "  --max-tasks <n>       run-loop 最多执行 n 个任务",
+    "  --max-attempts <n>    每种策略内最多重试 n 次",
+    "  --max-strategies <n>  单任务最多切换 n 种策略继续重试",
+    "  --allow-high-risk     允许执行 medium/high/critical 风险任务",
+    "  --required-doc <p>    增加一个全局必读文档（AGENTS.md 会被自动忽略）",
+    "  --constraint <text>   增加一个全局实现约束",
+  ].join("\n");
+}
+
+function printHelp() {
+  console.log(helpText());
+}
+
+function probeCodexVersion() {
+  const codexVersion = process.platform === "win32"
+    ? spawnSync("codex --version", {
+        encoding: "utf8",
+        shell: true,
+      })
+    : spawnSync("codex", ["--version"], {
+        encoding: "utf8",
+        shell: false,
+      });
+  const ok = codexVersion.status === 0;
+  return {
+    ok,
+    detail: ok
+      ? String(codexVersion.stdout || "").trim()
+      : String(codexVersion.stderr || codexVersion.error || "无法执行 codex --version").trim(),
+  };
+}
+
+function collectDoctorChecks(context) {
+  const codexVersion = probeCodexVersion();
+  return [
+    {
+      name: "codex CLI",
+      ok: codexVersion.ok,
+      detail: codexVersion.detail,
+    },
+    {
+      name: "backlog.json",
+      ok: fileExists(context.backlogFile),
+      detail: context.backlogFile,
+    },
+    {
+      name: "policy.json",
+      ok: fileExists(context.policyFile),
+      detail: context.policyFile,
+    },
+    {
+      name: "verify.yaml",
+      ok: fileExists(context.repoVerifyFile),
+      detail: context.repoVerifyFile,
+    },
+    {
+      name: "project.json",
+      ok: fileExists(context.projectFile),
+      detail: context.projectFile,
+    },
+    {
+      name: "plugin manifest",
+      ok: fileExists(context.pluginManifestFile),
+      detail: context.pluginManifestFile,
+    },
+    {
+      name: "plugin skill",
+      ok: fileExists(context.skillFile),
+      detail: context.skillFile,
+    },
+    {
+      name: "install script",
+      ok: fileExists(context.installScriptFile),
+      detail: context.installScriptFile,
+    },
+  ];
+}
+
+async function runDoctor(context) {
+  const checks = collectDoctorChecks(context);
+
+  for (const item of checks) {
+    console.log(`${item.ok ? "OK" : "FAIL"}  ${item.name}  ${item.detail}`);
+  }
+
+  if (checks.every((item) => item.ok)) {
+    console.log("\nDoctor 结论：当前 HelloLoop bundle 与目标仓库已具备基本运行条件。");
+  }
+
+  if (checks.some((item) => !item.ok)) {
+    process.exitCode = 1;
+  }
+}
+
+export async function runCli(argv) {
+  const { command, options } = parseArgs(argv);
+
+  if (command === "help" || command === "--help" || command === "-h") {
+    printHelp();
+    return;
+  }
+
+  const context = createContext({
+    repoRoot: options.repoRoot,
+    configDirName: options.configDirName,
+  });
+
+  if (command === "install") {
+    const result = installPluginBundle({
+      bundleRoot: context.bundleRoot,
+      codexHome: options.codexHome,
+      force: options.force,
+    });
+    console.log(`HelloLoop 已安装到：${result.targetPluginRoot}`);
+    console.log(`Marketplace 已更新：${result.marketplaceFile}`);
+    console.log("");
+    console.log("下一步示例：");
+    console.log(`node ${path.join(result.targetPluginRoot, "scripts", "helloloop.mjs")} doctor --repo D:\\GitHub\\dev\\your-repo`);
+    return;
+  }
+
+  if (command === "init") {
+    const created = scaffoldIfMissing(context);
+    if (!created.length) {
+      console.log("HelloLoop 配置已存在，无需初始化。");
+      return;
+    }
+    console.log([
+      "已初始化以下文件：",
+      ...created.map((item) => `- ${path.relative(context.repoRoot, item).replaceAll("\\", "/")}`),
+    ].join("\n"));
+    return;
+  }
+
+  if (command === "doctor") {
+    await runDoctor(context);
+    return;
+  }
+
+  if (command === "status") {
+    console.log(renderStatusText(context, options));
+    return;
+  }
+
+  if (command === "next") {
+    const result = await runOnce(context, { ...options, dryRun: true });
+    if (!result.task) {
+      console.log("当前没有可执行任务。");
+      return;
+    }
+    console.log([
+      "下一任务预览",
+      "============",
+      `任务：${result.task.title}`,
+      `编号：${result.task.id}`,
+      `运行目录：${result.runDir}`,
+      "",
+      "验证命令：",
+      ...result.verifyCommands.map((item) => `- ${item}`),
+      "",
+      "提示词：",
+      result.prompt,
+    ].join("\n"));
+    return;
+  }
+
+  if (command === "run-once") {
+    const result = await runOnce(context, options);
+    if (!result.ok) {
+      console.error(result.summary || "执行失败。");
+      process.exitCode = 1;
+      return;
+    }
+    if (options.dryRun) {
+      console.log(result.task
+        ? `已生成干跑预览：${result.task.title}\n运行目录：${result.runDir}`
+        : "当前没有可执行任务。");
+      return;
+    }
+    console.log(result.task
+      ? `完成任务：${result.task.title}\n运行目录：${result.runDir}`
+      : "没有可执行任务。");
+    return;
+  }
+
+  if (command === "run-loop") {
+    const results = await runLoop(context, options);
+    const failed = results.find((item) => !item.ok);
+    for (const item of results) {
+      if (!item.task) {
+        console.log("没有更多可执行任务。");
+        break;
+      }
+      console.log(`${item.ok ? "成功" : "失败"}：${item.task.title}`);
+    }
+    if (failed) {
+      console.error(failed.summary || "连续执行中断。");
+      process.exitCode = 1;
+    }
+    return;
+  }
+
+  throw new Error(`未知命令：${command}`);
+}
+

package/src/common.mjs

@@ -0,0 +1,66 @@
+import fs from "node:fs";
+import path from "node:path";
+
+export function ensureDir(dirPath) {
+  fs.mkdirSync(dirPath, { recursive: true });
+}
+
+export function fileExists(filePath) {
+  return fs.existsSync(filePath);
+}
+
+export function readText(filePath) {
+  return fs.readFileSync(filePath, "utf8");
+}
+
+export function readTextIfExists(filePath, fallback = "") {
+  return fileExists(filePath) ? readText(filePath) : fallback;
+}
+
+export function readJson(filePath) {
+  return JSON.parse(readText(filePath));
+}
+
+export function writeText(filePath, content) {
+  ensureDir(path.dirname(filePath));
+  fs.writeFileSync(filePath, content, "utf8");
+}
+
+export function writeJson(filePath, value) {
+  writeText(filePath, `${JSON.stringify(value, null, 2)}\n`);
+}
+
+export function nowIso() {
+  return new Date().toISOString();
+}
+
+export function timestampForFile(date = new Date()) {
+  return date.toISOString().replaceAll(":", "-").replaceAll(".", "-");
+}
+
+export function sanitizeId(value) {
+  return String(value || "")
+    .trim()
+    .toLowerCase()
+    .replace(/[^a-z0-9\u4e00-\u9fa5_-]+/g, "-")
+    .replace(/-+/g, "-")
+    .replace(/^-|-$/g, "") || "task";
+}
+
+export function tailText(text, maxLines = 60) {
+  const normalized = String(text || "").replaceAll("\r\n", "\n");
+  const lines = normalized.split("\n");
+  return lines.slice(Math.max(0, lines.length - maxLines)).join("\n").trim();
+}
+
+export function formatList(items) {
+  return items.map((item) => `- ${item}`).join("\n");
+}
+
+export function resolveFrom(rootDir, ...segments) {
+  return path.join(rootDir, ...segments);
+}
+
+export function normalizeRelative(rootDir, targetPath) {
+  return path.relative(rootDir, targetPath).replaceAll("\\", "/");
+}

package/src/config.mjs

@@ -0,0 +1,141 @@
+import path from "node:path";
+
+import {
+  fileExists,
+  nowIso,
+  readJson,
+  readTextIfExists,
+  writeJson,
+  writeText,
+} from "./common.mjs";
+
+const defaultPolicy = {
+  version: 1,
+  updatedAt: nowIso(),
+  maxLoopTasks: 4,
+  maxTaskAttempts: 2,
+  maxTaskStrategies: 4,
+  stopOnFailure: false,
+  stopOnHighRisk: true,
+  codex: {
+    model: "",
+    executable: "",
+    sandbox: "workspace-write",
+    dangerouslyBypassSandbox: false,
+    jsonOutput: true,
+  },
+};
+
+const defaultPlanner = {
+  minTasks: 3,
+  maxTasks: 8,
+  roleInference: true,
+  workflowHints: [
+    "先识别每份文档的角色和可信度，再组织主线。",
+    "优先输出可逐步开发、测试、验收的任务。",
+    "避免把整个文档目录压成一个大任务。",
+  ],
+};
+
+export function loadPolicy(context) {
+  const policy = {
+    ...defaultPolicy,
+    ...(fileExists(context.policyFile) ? readJson(context.policyFile) : {}),
+  };
+  policy.codex = {
+    ...defaultPolicy.codex,
+    ...(policy.codex || {}),
+  };
+  return policy;
+}
+
+export function loadProjectConfig(context) {
+  if (!fileExists(context.projectFile)) {
+    return {
+      requiredDocs: [],
+      constraints: [],
+      planner: defaultPlanner,
+    };
+  }
+
+  const config = readJson(context.projectFile);
+  return {
+    requiredDocs: Array.isArray(config.requiredDocs) ? config.requiredDocs : [],
+    constraints: Array.isArray(config.constraints) ? config.constraints : [],
+    planner: {
+      ...defaultPlanner,
+      ...(config.planner || {}),
+      workflowHints: Array.isArray(config?.planner?.workflowHints)
+        ? config.planner.workflowHints
+        : defaultPlanner.workflowHints,
+    },
+  };
+}
+
+export function loadBacklog(context) {
+  const backlog = readJson(context.backlogFile);
+  if (!backlog || !Array.isArray(backlog.tasks)) {
+    throw new Error("HelloLoop backlog 无效：缺少 tasks 数组。");
+  }
+  return backlog;
+}
+
+export function saveBacklog(context, backlog) {
+  writeJson(context.backlogFile, {
+    ...backlog,
+    updatedAt: nowIso(),
+  });
+}
+
+export function loadVerifyCommands(context) {
+  const raw = readTextIfExists(context.repoVerifyFile, "");
+  return raw
+    .split(/\r?\n/)
+    .map((line) => line.trimEnd())
+    .filter((line) => /^\s*-\s+/.test(line))
+    .map((line) => line.replace(/^\s*-\s+/, "").trim())
+    .filter(Boolean);
+}
+
+export function loadRepoStateText(context) {
+  return readTextIfExists(context.repoStateFile, "").trim();
+}
+
+export function writeStatus(context, status) {
+  writeJson(context.statusFile, {
+    ...status,
+    updatedAt: nowIso(),
+  });
+}
+
+export function writeStateMarkdown(context, content) {
+  writeText(context.stateFile, `${content.trim()}\n`);
+}
+
+export function scaffoldIfMissing(context) {
+  const files = [
+    ["backlog.template.json", context.backlogFile],
+    ["policy.template.json", context.policyFile],
+    ["project.template.json", context.projectFile],
+    ["status.template.json", context.statusFile],
+    ["STATE.template.md", context.stateFile],
+  ];
+
+  const created = [];
+  for (const [templateName, targetFile] of files) {
+    if (fileExists(targetFile)) continue;
+    const source = path.join(context.templatesDir, templateName);
+    const content = readTextIfExists(source, "");
+    writeText(targetFile, content);
+    created.push(targetFile);
+  }
+
+  const runsKeep = path.join(context.runsDir, ".gitkeep");
+  if (!fileExists(runsKeep)) {
+    writeText(runsKeep, "\n");
+    created.push(runsKeep);
+  }
+
+  return created;
+}
+

package/src/context.mjs

@@ -0,0 +1,56 @@
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+import { fileExists, resolveFrom } from "./common.mjs";
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+const toolRoot = path.resolve(__dirname, "..");
+const defaultConfigDirName = ".helloloop";
+const legacyConfigDirName = ".helloagents/helloloop";
+
+function resolveConfigDirName(repoRoot, explicitConfigDirName) {
+  if (explicitConfigDirName) {
+    return explicitConfigDirName;
+  }
+
+  const defaultConfigRoot = resolveFrom(repoRoot, ...defaultConfigDirName.split("/"));
+  if (fileExists(defaultConfigRoot)) {
+    return defaultConfigDirName;
+  }
+
+  const legacyConfigRoot = resolveFrom(repoRoot, ...legacyConfigDirName.split("/"));
+  if (fileExists(legacyConfigRoot)) {
+    return legacyConfigDirName;
+  }
+
+  return defaultConfigDirName;
+}
+
+export function createContext(options = {}) {
+  const repoRoot = path.resolve(options.repoRoot || process.cwd());
+  const configDirName = resolveConfigDirName(repoRoot, options.configDirName);
+  const configRoot = resolveFrom(repoRoot, ...configDirName.split("/"));
+
+  return {
+    repoRoot,
+    toolRoot,
+    bundleRoot: toolRoot,
+    templatesDir: resolveFrom(toolRoot, "templates"),
+    pluginManifestFile: resolveFrom(toolRoot, ".codex-plugin", "plugin.json"),
+    skillFile: resolveFrom(toolRoot, "skills", "helloloop", "SKILL.md"),
+    installScriptFile: resolveFrom(toolRoot, "scripts", "install-home-plugin.ps1"),
+    docsRoot: resolveFrom(toolRoot, "docs"),
+    configDirName,
+    configRoot,
+    backlogFile: resolveFrom(configRoot, "backlog.json"),
+    policyFile: resolveFrom(configRoot, "policy.json"),
+    projectFile: resolveFrom(configRoot, "project.json"),
+    statusFile: resolveFrom(configRoot, "status.json"),
+    stateFile: resolveFrom(configRoot, "STATE.md"),
+    runsDir: resolveFrom(configRoot, "runs"),
+    repoStateFile: resolveFrom(repoRoot, ".helloagents", "STATE.md"),
+    repoVerifyFile: resolveFrom(repoRoot, ".helloagents", "verify.yaml"),
+  };
+}
+

package/src/doc_loader.mjs

@@ -0,0 +1,106 @@
+import fs from "node:fs";
+import path from "node:path";
+
+const SUPPORTED_SUFFIX = new Set([
+  ".md",
+  ".markdown",
+  ".mdx",
+  ".txt",
+  ".rst",
+  ".adoc",
+]);
+
+function walkDocs(directoryPath, files) {
+  const entries = fs.readdirSync(directoryPath, { withFileTypes: true });
+  for (const entry of entries) {
+    const absolute = path.join(directoryPath, entry.name);
+    if (entry.isDirectory()) {
+      walkDocs(absolute, files);
+      continue;
+    }
+
+    if (SUPPORTED_SUFFIX.has(path.extname(entry.name).toLowerCase())) {
+      files.push(absolute);
+    }
+  }
+}
+
+function expandEntry(repoRoot, rawEntry) {
+  const absolute = path.isAbsolute(rawEntry)
+    ? rawEntry
+    : path.resolve(repoRoot, rawEntry);
+
+  if (!fs.existsSync(absolute)) {
+    return [];
+  }
+
+  const stat = fs.statSync(absolute);
+  if (stat.isFile()) {
+    return [absolute];
+  }
+
+  if (!stat.isDirectory()) {
+    return [];
+  }
+
+  const files = [];
+  walkDocs(absolute, files);
+  return files.sort((left, right) => left.localeCompare(right));
+}
+
+function normalizePath(repoRoot, absolutePath) {
+  const relative = path.relative(repoRoot, absolutePath);
+  if (!relative.startsWith("..")) {
+    return relative.replaceAll("\\", "/");
+  }
+
+  return absolutePath.replaceAll("\\", "/");
+}
+
+export function expandDocumentEntries(repoRoot, entries) {
+  const absoluteFiles = [];
+  for (const entry of entries || []) {
+    absoluteFiles.push(...expandEntry(repoRoot, entry));
+  }
+
+  const seen = new Set();
+  return absoluteFiles
+    .filter((absolutePath) => {
+      const key = absolutePath.toLowerCase();
+      if (seen.has(key)) {
+        return false;
+      }
+
+      seen.add(key);
+      return true;
+    })
+    .map((absolutePath) => ({
+      absolutePath,
+      relativePath: normalizePath(repoRoot, absolutePath),
+    }));
+}
+
+export function readDocumentPackets(repoRoot, entries, options = {}) {
+  const maxCharsPerFile = Number(options.maxCharsPerFile || 18000);
+  const maxTotalChars = Number(options.maxTotalChars || 90000);
+  let remaining = maxTotalChars;
+
+  const packets = [];
+  for (const file of expandDocumentEntries(repoRoot, entries)) {
+    if (remaining <= 0) {
+      break;
+    }
+
+    const fullText = fs.readFileSync(file.absolutePath, "utf8");
+    const sliceLength = Math.max(0, Math.min(fullText.length, maxCharsPerFile, remaining));
+    packets.push({
+      path: file.relativePath,
+      content: fullText.slice(0, sliceLength),
+      truncated: sliceLength < fullText.length,
+      chars: sliceLength,
+    });
+    remaining -= sliceLength;
+  }
+
+  return packets;
+}