helloloop 0.1.0

package/src/install.mjs

@@ -0,0 +1,130 @@
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+import { ensureDir, fileExists, readJson, writeJson } from "./common.mjs";
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+
+export const runtimeBundleEntries = [
+  ".codex-plugin",
+  "README.md",
+  "bin",
+  "package.json",
+  "scripts",
+  "skills",
+  "src",
+  "templates",
+];
+
+function resolveCodexHome(codexHome) {
+  return path.resolve(codexHome || path.join(os.homedir(), ".codex"));
+}
+
+function assertPathInside(parentDir, targetDir, label) {
+  const relative = path.relative(parentDir, targetDir);
+  if (!relative || relative.startsWith("..") || path.isAbsolute(relative)) {
+    throw new Error(`${label} 超出允许范围：${targetDir}`);
+  }
+}
+
+function copyBundleEntries(bundleRoot, targetPluginRoot) {
+  for (const entry of runtimeBundleEntries) {
+    const sourcePath = path.join(bundleRoot, entry);
+    if (!fileExists(sourcePath)) {
+      continue;
+    }
+
+    fs.cpSync(sourcePath, path.join(targetPluginRoot, entry), {
+      force: true,
+      recursive: true,
+    });
+  }
+}
+
+function updateMarketplace(marketplaceFile) {
+  const marketplace = fileExists(marketplaceFile)
+    ? readJson(marketplaceFile)
+    : {
+        name: "local-plugins",
+        interface: {
+          displayName: "Local Plugins",
+        },
+        plugins: [],
+      };
+
+  marketplace.interface = marketplace.interface || {
+    displayName: "Local Plugins",
+  };
+  marketplace.plugins = Array.isArray(marketplace.plugins) ? marketplace.plugins : [];
+
+  const nextEntry = {
+    name: "helloloop",
+    source: {
+      source: "local",
+      path: "./plugins/helloloop",
+    },
+    policy: {
+      installation: "AVAILABLE",
+      authentication: "ON_INSTALL",
+    },
+    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);
+  } else {
+    marketplace.plugins.push(nextEntry);
+  }
+
+  writeJson(marketplaceFile, marketplace);
+}
+
+export function installPluginBundle(options = {}) {
+  const bundleRoot = path.resolve(options.bundleRoot || path.join(__dirname, ".."));
+  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");
+
+  if (!fileExists(manifestFile)) {
+    throw new Error(`未找到插件 manifest：${manifestFile}`);
+  }
+
+  assertPathInside(resolvedCodexHome, targetPluginRoot, "目标插件目录");
+
+  if (fileExists(targetPluginRoot)) {
+    if (!options.force) {
+      throw new Error(`目标插件目录已存在：${targetPluginRoot}。若要覆盖，请追加 --force。`);
+    }
+    fs.rmSync(targetPluginRoot, { recursive: true, force: true });
+  }
+
+  if (fileExists(legacyPluginRoot)) {
+    fs.rmSync(legacyPluginRoot, { recursive: true, force: true });
+  }
+
+  ensureDir(targetPluginsRoot);
+  ensureDir(targetPluginRoot);
+  copyBundleEntries(bundleRoot, targetPluginRoot);
+
+  const gitMetadataPath = path.join(targetPluginRoot, ".git");
+  if (fileExists(gitMetadataPath)) {
+    fs.rmSync(gitMetadataPath, { recursive: true, force: true });
+  }
+
+  ensureDir(path.dirname(marketplaceFile));
+  updateMarketplace(marketplaceFile);
+
+  return {
+    targetPluginRoot,
+    marketplaceFile,
+  };
+}

package/src/lifecycle.mjs

@@ -0,0 +1,58 @@
+export const sessionStatus = Object.freeze({
+  running: "running",
+  needsInput: "needs_input",
+  done: "done",
+  stopped: "stopped",
+});
+
+export const turnState = Object.freeze({
+  ready: "ready",
+  done: "done",
+  blockedMissingBacklog: "blocked_missing_backlog",
+  blockedInProgress: "blocked_in_progress",
+  blockedFailed: "blocked_failed",
+  blockedRisk: "blocked_risk",
+  blockedDependencies: "blocked_dependencies",
+});
+
+const turnStateLabels = Object.freeze({
+  [turnState.ready]: "可执行",
+  [turnState.done]: "已完成",
+  [turnState.blockedMissingBacklog]: "缺少 backlog",
+  [turnState.blockedInProgress]: "存在未收束任务",
+  [turnState.blockedFailed]: "存在失败或阻塞任务",
+  [turnState.blockedRisk]: "风险门限阻塞",
+  [turnState.blockedDependencies]: "依赖阻塞",
+});
+
+export function isBlockedTurnState(state) {
+  return String(state || "").startsWith("blocked_");
+}
+
+export function isReadyTurnState(state) {
+  return String(state || "") === turnState.ready;
+}
+
+export function isDoneTurnState(state) {
+  return String(state || "") === turnState.done;
+}
+
+export function renderTurnStateLabel(state) {
+  return turnStateLabels[String(state || "")] || "未知状态";
+}
+
+export function deriveSessionStatusFromTurnState(state) {
+  if (isReadyTurnState(state)) {
+    return sessionStatus.running;
+  }
+
+  if (isDoneTurnState(state)) {
+    return sessionStatus.done;
+  }
+
+  if (isBlockedTurnState(state)) {
+    return sessionStatus.needsInput;
+  }
+
+  return sessionStatus.needsInput;
+}

package/src/process.mjs

@@ -0,0 +1,264 @@
+import fs from "node:fs";
+import path from "node:path";
+import { spawn, spawnSync } from "node:child_process";
+
+import { ensureDir, nowIso, tailText, writeText } from "./common.mjs";
+
+function runChild(command, args, options = {}) {
+  return new Promise((resolve) => {
+    const child = spawn(command, args, {
+      cwd: options.cwd,
+      env: {
+        ...process.env,
+        ...(options.env || {}),
+      },
+      stdio: ["pipe", "pipe", "pipe"],
+      shell: Boolean(options.shell),
+    });
+
+    let stdout = "";
+    let stderr = "";
+
+    child.stdout.on("data", (chunk) => {
+      stdout += chunk.toString();
+    });
+    child.stderr.on("data", (chunk) => {
+      stderr += chunk.toString();
+    });
+
+    if (options.stdin) {
+      child.stdin.write(options.stdin);
+    }
+    child.stdin.end();
+
+    child.on("error", (error) => {
+      resolve({
+        ok: false,
+        code: 1,
+        stdout,
+        stderr: String(error?.stack || error || ""),
+      });
+    });
+
+    child.on("close", (code) => {
+      resolve({
+        ok: code === 0,
+        code: code ?? 1,
+        stdout,
+        stderr,
+      });
+    });
+  });
+}
+
+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 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);
+  writeText(path.join(runDir, `${prefix}-summary.txt`), [
+    `ok=${result.ok}`,
+    `code=${result.code}`,
+    `finished_at=${nowIso()}`,
+    "",
+    finalMessage,
+  ].join("\n"));
+}
+
+export async function runCodexTask({
+  context,
+  prompt,
+  runDir,
+  model = "",
+  executable = "",
+  sandbox = "workspace-write",
+  dangerouslyBypassSandbox = false,
+  jsonOutput = true,
+  outputSchemaFile = "",
+  outputPrefix = "codex",
+  ephemeral = false,
+  skipGitRepoCheck = false,
+  env = {},
+}) {
+  ensureDir(runDir);
+
+  const lastMessageFile = path.join(runDir, `${outputPrefix}-last-message.txt`);
+  const invocation = resolveCodexInvocation(executable);
+  const codexArgs = ["exec", "-C", context.repoRoot];
+
+  if (model) {
+    codexArgs.push("--model", model);
+  }
+  if (dangerouslyBypassSandbox) {
+    codexArgs.push("--dangerously-bypass-approvals-and-sandbox");
+  } else {
+    codexArgs.push("--sandbox", sandbox);
+  }
+  if (skipGitRepoCheck) {
+    codexArgs.push("--skip-git-repo-check");
+  }
+  if (ephemeral) {
+    codexArgs.push("--ephemeral");
+  }
+  if (outputSchemaFile) {
+    codexArgs.push("--output-schema", outputSchemaFile);
+  }
+  if (jsonOutput) {
+    codexArgs.push("--json");
+  }
+  codexArgs.push("-o", lastMessageFile, "-");
+
+  const args = invocation.executable
+    ? [...invocation.argsPrefix, buildCmdCommandLine(invocation.executable, codexArgs)]
+    : [...invocation.argsPrefix, ...codexArgs];
+
+  const result = await runChild(invocation.command, args, {
+    cwd: context.repoRoot,
+    stdin: prompt,
+    env,
+    shell: invocation.shell,
+  });
+  const finalMessage = fs.existsSync(lastMessageFile)
+    ? fs.readFileSync(lastMessageFile, "utf8").trim()
+    : "";
+
+  writeText(path.join(runDir, `${outputPrefix}-prompt.md`), prompt);
+  writeCodexRunArtifacts(runDir, outputPrefix, result, finalMessage);
+
+  return { ...result, finalMessage };
+}
+
+export async function runCodexExec({ context, prompt, runDir, policy }) {
+  return runCodexTask({
+    context,
+    prompt,
+    runDir,
+    model: policy.codex.model,
+    executable: policy.codex.executable,
+    sandbox: policy.codex.sandbox,
+    dangerouslyBypassSandbox: policy.codex.dangerouslyBypassSandbox,
+    jsonOutput: policy.codex.jsonOutput,
+    outputPrefix: "codex",
+  });
+}
+
+export async function runShellCommand(context, commandLine, runDir, index) {
+  const result = await runChild("pwsh", [
+    "-NoLogo",
+    "-NoProfile",
+    "-Command",
+    commandLine,
+  ], {
+    cwd: context.repoRoot,
+  });
+
+  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 { command: commandLine, ...result };
+}
+
+export async function runVerifyCommands(context, commands, runDir) {
+  const results = [];
+
+  for (const [index, command] of commands.entries()) {
+    const result = await runShellCommand(context, command, runDir, index);
+    results.push(result);
+    if (!result.ok) {
+      return {
+        ok: false,
+        results,
+        failed: result,
+        summary: [
+          `验证失败：${result.command}`,
+          "",
+          "stdout 尾部：",
+          tailText(result.stdout, 40),
+          "",
+          "stderr 尾部：",
+          tailText(result.stderr, 40),
+        ].join("\n").trim(),
+      };
+    }
+  }
+
+  return {
+    ok: true,
+    results,
+    failed: null,
+    summary: "全部验证命令通过。",
+  };
+}

package/src/prompt.mjs

@@ -0,0 +1,116 @@
+import { formatList } from "./common.mjs";
+
+function normalizeDocEntry(doc) {
+  return String(doc || "").trim().replaceAll("\\", "/");
+}
+
+function isAgentsDoc(doc) {
+  const normalized = normalizeDocEntry(doc).toLowerCase();
+  if (!normalized) {
+    return false;
+  }
+
+  const segments = normalized.split("/");
+  return segments[segments.length - 1] === "agents.md";
+}
+
+function normalizeDocList(items) {
+  const result = [];
+  const seen = new Set();
+
+  for (const item of items || []) {
+    const normalized = normalizeDocEntry(item);
+    if (!normalized || isAgentsDoc(normalized)) {
+      continue;
+    }
+
+    const key = normalized.toLowerCase();
+    if (seen.has(key)) {
+      continue;
+    }
+
+    seen.add(key);
+    result.push(normalized);
+  }
+
+  return result;
+}
+
+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));
+}
+
+export function buildTaskPrompt({
+  task,
+  repoStateText,
+  verifyCommands,
+  requiredDocs = [],
+  constraints = [],
+  previousFailure = "",
+  failureHistory = [],
+  strategyIndex = 1,
+  maxStrategies = 1,
+  attemptIndex = 1,
+  maxAttemptsPerStrategy = 1,
+}) {
+  const allDocs = normalizeDocList([
+    ...requiredDocs,
+    ...(task.docs || []),
+  ]);
+
+  const effectiveConstraints = constraints.length
+    ? constraints
+    : [
+        "所有文件修改必须用 apply_patch。",
+        "不得通过压缩代码、删空行、缩短命名来压行数。",
+        "Rust / TS / TSX / Vue / Python / Go 单文件强制拆分上限 400 行。",
+        "新增可见文案必须同时补齐 zh-CN 与 en-US。",
+        "完成后必须同步相关中文文档与联调文档。",
+        "完成前必须主动运行验证，不要停在分析层。",
+      ];
+
+  return [
+    "你在本地仓库中执行一个连续开发任务。",
+    "必须严格按仓库开发文档推进，不要偏离产品路线。",
+    "当前执行模式是 Ralph Loop：失败后先修复重试，连续失败后必须换一种思路继续。",
+    "",
+    listSection("开发前必读", allDocs),
+    section("当前循环阶段", [
+      `- 当前策略轮次：${strategyIndex}/${maxStrategies}`,
+      `- 当前策略内重试：${attemptIndex}/${maxAttemptsPerStrategy}`,
+      strategyIndex > 1 ? "- 这是换路后的新一轮尝试，禁止简单重复上一轮做法。" : "",
+    ].filter(Boolean).join("\n")),
+    section("当前任务", [
+      `- 标题：${task.title}`,
+      `- 编号：${task.id}`,
+      `- 优先级：${task.priority || "P2"}`,
+      `- 风险等级：${task.risk || "low"}`,
+      `- 目标：${task.goal || "按文档完成当前工作包。"}`,
+    ].join("\n")),
+    listSection("涉及路径", task.paths || []),
+    listSection("验收条件", task.acceptance || []),
+    listSection("实现约束", effectiveConstraints),
+    repoStateText ? section("仓库当前状态", repoStateText) : "",
+    failureHistory.length
+      ? section("已失败尝试摘要", failureHistory.slice(-4).map((item) => (
+        `- 策略 ${item.strategyIndex} / 尝试 ${item.attemptIndex} / ${item.kind}：${item.summary}`
+      )).join("\n"))
+      : "",
+    previousFailure ? section("上一轮失败信息", previousFailure) : "",
+    listSection("完成前必须运行的验证", verifyCommands),
+    section("交付要求", [
+      "1. 直接在仓库中完成实现。",
+      "2. 运行验证；若失败，先分析根因，再修复并重跑。",
+      "3. 同一路径连续失败后，必须明确换一种实现或排查思路。",
+      "4. 除非遇到外部权限、环境损坏、文档缺口等硬阻塞，否则不要停止。",
+      "5. 用简洁中文总结变更、验证结果和剩余风险。",
+      "6. 不要提问，不要等待确认，直接完成。",
+    ].join("\n")),
+  ].filter(Boolean).join("\n");
+}