@gaberrb/polypus 0.2.0 → 0.2.2

package/README.md

@@ -4,7 +4,7 @@
 [![npm](https://img.shields.io/npm/v/@gaberrb/polypus?color=9266F5&logo=npm)](https://www.npmjs.com/package/@gaberrb/polypus)
 [![license](https://img.shields.io/badge/license-MIT-AB8EFA)](LICENSE)
 
-**📖 Site:** https://gaberrb.github.io/polypus/ · **📦 npm:** [`@gaberrb/polypus`](https://www.npmjs.com/package/@gaberrb/polypus)
+**📖 Site:** https://gaberrb.github.io/polypus/ · **📦 npm:** [`@gaberrb/polypus`](https://www.npmjs.com/package/@gaberrb/polypus) · **📝 Changelog:** [CHANGELOG.md](https://github.com/GaberRB/polypus/blob/main/CHANGELOG.md)
 
 An agentic coding harness that makes **any** AI API generate and apply code —
 even models **without** native tool-calling. Bring your own keys: OpenRouter,

package/dist/index.js

@@ -2,7 +2,8 @@
 
 // src/cli/index.ts
 import { Command } from "commander";
-import pc10 from "picocolors";
+import { createRequire } from "module";
+import pc12 from "picocolors";
 
 // src/cli/commands/add-agent.ts
 import pc from "picocolors";
@@ -79,6 +80,16 @@ var en = {
   "cli.cmd.run": "Run a coding task with an agent",
   "cli.cmd.swarm": "Split a task across multiple agents working in parallel git worktrees",
   "cli.cmd.models": "Browse OpenRouter models (price, context, tool support)",
+  "cli.cmd.prd": "Generate a PRD from a GitHub issue (uses a free OpenRouter model)",
+  "cli.arg.prdIssue": "issue number to turn into a PRD",
+  "cli.cmd.review": "Review a pull request diff (uses a free OpenRouter model)",
+  "cli.arg.reviewPr": "pull request number to review",
+  "cli.opt.out": "write output to this file instead of stdout",
+  "cli.opt.input": 'read input from a file (or "-" for stdin) instead of calling gh',
+  "prd.wrote": "\u2713 PRD written to {path}",
+  "review.wrote": "\u2713 Review written to {path}",
+  "cli.invalidRef": "Invalid number '{ref}': expected a numeric issue/PR number.",
+  "cli.stdinTty": "--input - expects piped stdin, but none was provided.",
   "cli.opt.search": "filter by id/name substring",
   "cli.opt.toolsOnly": "only models that support tool-calling",
   "cli.opt.free": "only free models",
@@ -269,6 +280,16 @@ var ptBR = {
   "cli.cmd.run": "Executa uma tarefa de c\xF3digo com um agente",
   "cli.cmd.swarm": "Divide uma tarefa entre v\xE1rios agentes trabalhando em paralelo em git worktrees",
   "cli.cmd.models": "Explora os modelos do OpenRouter (pre\xE7o, contexto, suporte a tools)",
+  "cli.cmd.prd": "Gera um PRD a partir de uma issue do GitHub (usa um modelo gratuito do OpenRouter)",
+  "cli.arg.prdIssue": "n\xFAmero da issue para transformar em PRD",
+  "cli.cmd.review": "Revisa o diff de um pull request (usa um modelo gratuito do OpenRouter)",
+  "cli.arg.reviewPr": "n\xFAmero do pull request a revisar",
+  "cli.opt.out": "grava a sa\xEDda neste arquivo em vez do stdout",
+  "cli.opt.input": 'l\xEA a entrada de um arquivo (ou "-" para stdin) em vez de chamar o gh',
+  "prd.wrote": "\u2713 PRD gravado em {path}",
+  "review.wrote": "\u2713 Review gravado em {path}",
+  "cli.invalidRef": "N\xFAmero inv\xE1lido '{ref}': esperado um n\xFAmero de issue/PR.",
+  "cli.stdinTty": "--input - espera entrada via pipe (stdin), mas nenhuma foi fornecida.",
   "cli.opt.search": "filtra por trecho do id/nome",
   "cli.opt.toolsOnly": "apenas modelos com suporte a tool-calling",
   "cli.opt.free": "apenas modelos gratuitos",
@@ -1447,6 +1468,14 @@ function getTool(name) {
 // src/core/agent/correction.ts
 import { readFile as readFile4, readdir as readdir2 } from "fs/promises";
 import { dirname as dirname2, resolve as resolve6 } from "path";
+function truncationGuidance(toolName) {
+  const fileHint = toolName === "write_file" || toolName === "edit_file" ? " Write large files in parts: create the file with the first chunk via write_file, then append the rest with edit_file in the next steps." : "";
+  return [
+    "AUTO-CORRECTION \u2014 your previous response was cut off at the output token limit,",
+    "so the tool call was incomplete (e.g. 'content' missing or partial).",
+    "Do NOT resend the same large output \u2014 produce a smaller one this time." + fileHint
+  ].join("\n");
+}
 async function buildCorrection(call, output, deps) {
   const deterministic = await deterministicCorrection(call, output, deps);
   if (deterministic) return deterministic;
@@ -1454,6 +1483,7 @@ async function buildCorrection(call, output, deps) {
   return null;
 }
 async function deterministicCorrection(call, output, deps) {
+  if (deps.truncated) return truncationGuidance(call.name);
   const path = typeof call.arguments.path === "string" ? call.arguments.path : void 0;
   if (call.name === "edit_file" && /was not found/i.test(output) && path) {
     const search = typeof call.arguments.search === "string" ? call.arguments.search : "";
@@ -1693,7 +1723,18 @@ async function runAgent(opts) {
     const { toolCalls, text: text2 } = driver.parse(response);
     messages.push(driver.assistantMessage(response, toolCalls));
     if (text2) events?.onAssistantText?.(text2);
+    const truncated = response.finishReason === "length" || response.finishReason === "max_tokens";
     if (toolCalls.length === 0) {
+      if (truncated && autoCorrect) {
+        if (consecutiveNoTool < maxReprompts) {
+          consecutiveNoTool++;
+          const guidance = truncationGuidance();
+          events?.onCorrection?.({ id: "trunc", name: "", arguments: {} }, guidance);
+          messages.push({ role: "user", content: guidance });
+          continue;
+        }
+        return { finished: false, reason: "stalled", steps: step, messages, usage };
+      }
       const stalled = text2.trim().length === 0 || looksLikeStall(text2);
       if (stalled) {
         if (consecutiveNoTool < maxReprompts) {
@@ -1724,6 +1765,7 @@ async function runAgent(opts) {
           workspace: opts.workspace,
           allow: opts.promptContext.allow,
           toolSpec: tool?.spec,
+          truncated,
           // Only spend a fixer-LLM call once the model has already repeated a
           // failing call — the first failure gets deterministic help for free.
           escalate: sig === lastFailSig ? makeLLMEscalator(agent.provider) : void 0
@@ -1734,6 +1776,12 @@ async function runAgent(opts) {
 ${guidance}`;
           events?.onCorrection?.(call, guidance);
         }
+      } else if (result.ok && truncated && autoCorrect) {
+        const guidance = truncationGuidance(call.name);
+        resultText = `${result.output}
+
+${guidance}`;
+        events?.onCorrection?.(call, guidance);
       }
       messages.push(driver.toolResultMessage(call, resultText));
       if (result.ok) {
@@ -2907,6 +2955,221 @@ async function resolveOpenRouterKey() {
   }
 }
 
+// src/cli/commands/prd.ts
+import { writeFile as writeFile4, readFile as readFile5 } from "fs/promises";
+import { execFile } from "child_process";
+import { promisify as promisify2 } from "util";
+import pc10 from "picocolors";
+
+// src/core/agent/prd.ts
+var SYSTEM = [
+  "You are a product analyst. You turn a GitHub issue into a concise, structured PRD",
+  "(Product Requirements Document) in Markdown.",
+  "Rules:",
+  "- Use ONLY information present in the issue and its comments. Do NOT invent scope,",
+  "  numbers, deadlines, or stakeholders. If something is unknown, write 'A definir'.",
+  "- Be objective and short; prefer bullet points over prose.",
+  "- Write in the same language as the issue (Portuguese if the issue is in Portuguese)."
+].join("\n");
+function buildPrdPrompt(issue) {
+  const comments = (issue.comments ?? []).map((c, i) => `Coment\xE1rio ${i + 1}${c.author ? ` (@${c.author})` : ""}:
+${c.body}`).join("\n\n");
+  return [
+    `Issue${issue.number ? ` #${issue.number}` : ""}: ${issue.title}`,
+    "",
+    "Corpo:",
+    issue.body || "(vazio)",
+    comments ? `
+${comments}` : "",
+    "",
+    "Gere um PRD com EXATAMENTE estas se\xE7\xF5es (H2 com ##):",
+    "## Contexto / Problema",
+    "## Objetivo",
+    "## Escopo (in / out)",
+    "## Requisitos funcionais",
+    "## Crit\xE9rios de aceite",
+    "## Riscos e alternativas"
+  ].join("\n");
+}
+async function generatePrd(issue, provider) {
+  const res = await provider.chat({
+    messages: [
+      { role: "system", content: SYSTEM },
+      { role: "user", content: buildPrdPrompt(issue) }
+    ],
+    params: { maxTokens: 2e3, temperature: 0.2 }
+  });
+  const text2 = res.content.trim();
+  if (!text2) throw new Error("The model returned an empty PRD.");
+  return text2;
+}
+
+// src/core/agent/free-provider.ts
+function resolveFreeProvider(model) {
+  if (!process.env.OPENROUTER_API_KEY) {
+    throw new Error(
+      "OPENROUTER_API_KEY is not set. Export it (or add it as a repo secret in CI) before running this command."
+    );
+  }
+  const config = {
+    name: "openrouter-free",
+    provider: "openrouter",
+    model,
+    apiKey: "${OPENROUTER_API_KEY}",
+    toolMode: "native"
+  };
+  return createProvider(config);
+}
+var DEFAULT_PRD_MODEL = process.env.POLYPUS_PRD_MODEL ?? "openai/gpt-oss-120b:free";
+var DEFAULT_REVIEW_MODEL = process.env.POLYPUS_REVIEW_MODEL ?? "openai/gpt-oss-120b:free";
+async function withRetry(fn, opts = {}) {
+  const attempts = opts.attempts ?? 4;
+  const baseMs = opts.baseMs ?? 2e3;
+  let lastErr;
+  for (let i = 0; i < attempts; i++) {
+    try {
+      return await fn();
+    } catch (err) {
+      lastErr = err;
+      const msg = err?.message ?? "";
+      const transient = /\b429\b|\b5\d\d\b|rate|timeout|ETIMEDOUT|ECONNRESET|EAI_AGAIN/i.test(msg);
+      if (!transient || i === attempts - 1) throw err;
+      await new Promise((r) => setTimeout(r, baseMs * 2 ** i));
+    }
+  }
+  throw lastErr;
+}
+
+// src/cli/commands/cli-io.ts
+function numericRef(ref) {
+  const num = ref.replace(/^#/, "");
+  if (!/^\d+$/.test(num)) throw new Error(t("cli.invalidRef", { ref }));
+  return num;
+}
+async function readStdin() {
+  if (process.stdin.isTTY) throw new Error(t("cli.stdinTty"));
+  const chunks = [];
+  for await (const chunk of process.stdin) chunks.push(chunk);
+  return Buffer.concat(chunks).toString("utf8");
+}
+function stripBom(s) {
+  return s.charCodeAt(0) === 65279 ? s.slice(1) : s;
+}
+
+// src/cli/commands/prd.ts
+var exec2 = promisify2(execFile);
+async function prd(issueRef, opts) {
+  const issue = await loadIssue(issueRef, opts.input);
+  const { provider } = resolveFreeProvider(opts.model ?? DEFAULT_PRD_MODEL);
+  const markdown = await withRetry(() => generatePrd(issue, provider));
+  if (opts.out) {
+    await writeFile4(opts.out, markdown + "\n", "utf8");
+    console.error(pc10.green(t("prd.wrote", { path: opts.out })));
+  } else {
+    process.stdout.write(markdown + "\n");
+  }
+}
+async function loadIssue(issueRef, input) {
+  if (input) {
+    const raw = input === "-" ? await readStdin() : await readFile5(input, "utf8");
+    return normalize2(JSON.parse(stripBom(raw)));
+  }
+  const num = numericRef(issueRef);
+  const { stdout: stdout2 } = await exec2("gh", ["issue", "view", num, "--json", "number,title,body,comments"]);
+  const data = normalize2(JSON.parse(stdout2));
+  data.number ??= Number(num);
+  return data;
+}
+function normalize2(raw) {
+  return {
+    number: raw.number,
+    title: raw.title ?? "",
+    body: raw.body ?? "",
+    comments: (raw.comments ?? []).map((c) => ({ author: c.author?.login, body: c.body ?? "" }))
+  };
+}
+
+// src/cli/commands/review.ts
+import { writeFile as writeFile5, readFile as readFile6 } from "fs/promises";
+import { execFile as execFile2 } from "child_process";
+import { promisify as promisify3 } from "util";
+import pc11 from "picocolors";
+
+// src/core/agent/review.ts
+var MAX_DIFF_CHARS = Number(process.env.POLYPUS_MAX_DIFF_CHARS) || 6e4;
+var SYSTEM2 = [
+  "You are a senior code reviewer. Review the pull request diff below and report",
+  "concrete findings in Markdown.",
+  "Rules:",
+  "- Focus on correctness bugs, security risks, and clear, actionable improvements.",
+  "- Reference file paths (and line hints when visible) so findings are easy to locate.",
+  "- Be concise. Skip style nitpicks unless they hide a real problem.",
+  "- If there are no relevant problems, say so briefly instead of inventing issues.",
+  "- Write in the same language as the PR description (Portuguese if it is in Portuguese)."
+].join("\n");
+function clampDiff(diff, max = MAX_DIFF_CHARS) {
+  if (diff.length <= max) return diff;
+  const dropped = diff.length - max;
+  return `${diff.slice(0, max)}
+
+\u2026 [diff truncado: ${dropped} caracteres omitidos para caber no contexto do modelo]`;
+}
+function buildReviewPrompt(diff, meta) {
+  return [
+    `PR${meta.number ? ` #${meta.number}` : ""}: ${meta.title}`,
+    "",
+    "Descri\xE7\xE3o:",
+    meta.body || "(vazia)",
+    "",
+    "Diff:",
+    "```diff",
+    clampDiff(diff),
+    "```",
+    "",
+    "Liste os achados agrupados por severidade (\u{1F534} bug, \u{1F7E1} aten\xE7\xE3o, \u{1F7E2} sugest\xE3o)."
+  ].join("\n");
+}
+async function reviewDiff(diff, meta, provider) {
+  if (!diff.trim()) return "_Sem altera\xE7\xF5es no diff para revisar._";
+  const res = await provider.chat({
+    messages: [
+      { role: "system", content: SYSTEM2 },
+      { role: "user", content: buildReviewPrompt(diff, meta) }
+    ],
+    params: { maxTokens: 1500, temperature: 0.2 }
+  });
+  const text2 = res.content.trim();
+  if (!text2) throw new Error("The model returned an empty review.");
+  return text2;
+}
+
+// src/cli/commands/review.ts
+var exec3 = promisify3(execFile2);
+async function review(prRef, opts) {
+  const num = opts.input ? prRef.replace(/^#/, "") : numericRef(prRef);
+  const diff = await loadDiff(num, opts.input);
+  const meta = await loadMeta(num, opts.input);
+  const { provider } = resolveFreeProvider(opts.model ?? DEFAULT_REVIEW_MODEL);
+  const markdown = await withRetry(() => reviewDiff(diff, meta, provider));
+  if (opts.out) {
+    await writeFile5(opts.out, markdown + "\n", "utf8");
+    console.error(pc11.green(t("review.wrote", { path: opts.out })));
+  } else {
+    process.stdout.write(markdown + "\n");
+  }
+}
+async function loadDiff(num, input) {
+  if (input) return input === "-" ? readStdin() : readFile6(input, "utf8");
+  const { stdout: stdout2 } = await exec3("gh", ["pr", "diff", num]);
+  return stdout2;
+}
+async function loadMeta(num, input) {
+  if (input) return { number: Number(num) || void 0, title: `PR ${num}`, body: "" };
+  const { stdout: stdout2 } = await exec3("gh", ["pr", "view", num, "--json", "number,title,body"]);
+  const raw = JSON.parse(stdout2);
+  return { number: raw.number, title: raw.title ?? "", body: raw.body ?? "" };
+}
+
 // src/cli/index.ts
 import { join as join3 } from "path";
 
@@ -2937,11 +3200,12 @@ function loadDotenv(paths) {
 }
 
 // src/cli/index.ts
+var { version: pkgVersion } = createRequire(import.meta.url)("../package.json");
 async function launchInteractive() {
   const config = await loadConfig();
   if (config.agents.length === 0) {
     console.log(banner());
-    console.log("  " + pc10.yellow(t("welcome.firstRun")) + "\n");
+    console.log("  " + pc12.yellow(t("welcome.firstRun")) + "\n");
     await setup();
   }
   await run(void 0, {});
@@ -2962,7 +3226,7 @@ async function resolveLocale() {
 }
 function buildProgram() {
   const program = new Command();
-  program.name("polypus").description(t("cli.description")).version("0.1.0").option("--lang <locale>", t("cli.opt.lang")).action(() => launchInteractive());
+  program.name("polypus").description(t("cli.description")).version(pkgVersion).option("--lang <locale>", t("cli.opt.lang")).action(() => launchInteractive());
   program.command("setup").description(t("cli.cmd.setup")).action(() => setup());
   program.command("add-agent").argument("<name>", t("cli.arg.addAgentName")).requiredOption("--provider <provider>", t("cli.opt.provider")).requiredOption("--model <model>", t("cli.opt.model")).option("--api-key <key>", t("cli.opt.apiKey")).option("--base-url <url>", t("cli.opt.baseUrl")).option("--tool-mode <mode>", t("cli.opt.toolMode"), "auto").option("--set-default", t("cli.opt.setDefault")).description(t("cli.cmd.addAgent")).action((name, opts) => addAgent(name, opts));
   program.command("remove-agent").argument("<name>", t("cli.arg.removeAgentName")).description(t("cli.cmd.removeAgent")).action((name) => removeAgent(name));
@@ -2970,6 +3234,8 @@ function buildProgram() {
   program.command("run").argument("[task]", t("cli.arg.runTask")).option("--agent <name>", t("cli.opt.agent")).option("--mode <mode>", t("cli.opt.mode")).option("--max-steps <n>", t("cli.opt.maxSteps")).description(t("cli.cmd.run")).action((task, opts) => run(task, opts));
   program.command("swarm").argument("<task>", t("cli.arg.swarmTask")).option("--agents <names>", t("cli.opt.agents")).option("--max-subtasks <n>", t("cli.opt.maxSubtasks")).description(t("cli.cmd.swarm")).action((task, opts) => swarm(task, opts));
   program.command("models").option("--search <text>", t("cli.opt.search")).option("--tools", t("cli.opt.toolsOnly")).option("--free", t("cli.opt.free")).option("--max-price <usd>", t("cli.opt.maxPrice")).option("--sort <order>", t("cli.opt.sort")).option("--limit <n>", t("cli.opt.limit")).description(t("cli.cmd.models")).action((opts) => models(opts));
+  program.command("prd").argument("<issue>", t("cli.arg.prdIssue")).option("--out <file>", t("cli.opt.out")).option("--model <model>", t("cli.opt.model")).option("--input <file>", t("cli.opt.input")).description(t("cli.cmd.prd")).action((issue, opts) => prd(issue, opts));
+  program.command("review").argument("<pr>", t("cli.arg.reviewPr")).option("--out <file>", t("cli.opt.out")).option("--model <model>", t("cli.opt.model")).option("--input <file>", t("cli.opt.input")).description(t("cli.cmd.review")).action((pr, opts) => review(pr, opts));
   return program;
 }
 async function main() {
@@ -2978,7 +3244,7 @@ async function main() {
     await resolveLocale();
     await buildProgram().parseAsync(process.argv);
   } catch (err) {
-    console.error(pc10.red(`\u2717 ${err.message}`));
+    console.error(pc12.red(`\u2717 ${err.message}`));
     process.exitCode = 1;
   }
 }