jarvis-ai-framework 2.1.0 → 3.0.0

package/bin/lib/flow-map/parse.js

@@ -0,0 +1,223 @@
+/**
+ * @fileoverview Leitor das declarações padronizadas de chamadas.
+ *
+ * Só lê a estrutura (sem interpretar prosa, sem IA):
+ * - workflows e skills: tabela `| Passo | Skill | Condição |` sob
+ *   `### Skills invocados durante o workflow` (ou `... durante a execução do skill`);
+ * - agentes: `## Skills Disponíveis` (`### {skill}`) e `## Workflows e Agentes Relacionados`.
+ * @module flow-map/parse
+ */
+
+export const WORKFLOW_TITLE = "Skills invocados durante o workflow";
+export const SKILL_TITLE = "Skills invocados durante a execução do skill";
+
+/**
+ * @typedef {Object} Target
+ * @property {"internal" | "agent" | "cli" | "mcp" | "external" | "unresolved"} kind
+ * @property {string} name
+ */
+
+/**
+ * @typedef {Object} Row
+ * @property {string | null} passo
+ * @property {string} condicao
+ * @property {Target[]} targets
+ * @property {string | null} via - Texto de `(via ...)`, quando houver
+ * @property {"quebrada" | "a confirmar" | null} marker
+ * @property {boolean} selfContained - Linha "Nenhuma — … autocontido"
+ * @property {boolean} available - Skill que o agente pode usar (não é chamada fixa)
+ */
+
+/** Troca o conteúdo dos blocos de código por linhas em branco (títulos dentro deles não valem). */
+function stripFences(text) {
+  let fence = false;
+  return text
+    .split("\n")
+    .map((line) => {
+      if (line.trimStart().startsWith("```")) {
+        fence = !fence;
+        return "";
+      }
+      return fence ? "" : line;
+    })
+    .join("\n");
+}
+
+/** Divide uma linha de tabela em células, ignorando `|` dentro de crases. */
+export function splitCells(line) {
+  const cells = [];
+  let current = "";
+  let inCode = false;
+  for (const ch of line.trim()) {
+    if (ch === "`") inCode = !inCode;
+    if (ch === "|" && !inCode) {
+      cells.push(current.trim());
+      current = "";
+    } else {
+      current += ch;
+    }
+  }
+  cells.push(current.trim());
+  if (cells[0] === "") cells.shift();
+  if (cells[cells.length - 1] === "") cells.pop();
+  return cells;
+}
+
+/**
+ * Classifica a célula `Skill` de uma linha da tabela.
+ * @param {string} cell
+ * @returns {{ targets: Target[], via: string | null, marker: Row["marker"], selfContained: boolean }}
+ */
+export function classifyCell(cell) {
+  const text = cell.trim();
+  if (/^nenhuma/i.test(text)) return { targets: [], via: null, marker: null, selfContained: true };
+
+  const marker = /refer[eê]ncia quebrada/i.test(text)
+    ? "quebrada"
+    : /refer[eê]ncia a confirmar/i.test(text)
+      ? "a confirmar"
+      : null;
+
+  let via = null;
+  let analyzed = text;
+  const viaMatch = text.match(/\(via\s+([^)]*)\)/);
+  if (viaMatch) {
+    via = viaMatch[1].replace(/`/g, "").trim();
+    analyzed = text.replace(viaMatch[0], "");
+  }
+
+  const spans = [...analyzed.matchAll(/`([^`]+)`(\s*\(agente\))?/g)];
+  const targets = [];
+  const external = /skill externo/i.test(analyzed); // skill de fora do framework: não está no índice
+
+  if (/\(MCP/.test(analyzed) && spans[0]) {
+    targets.push({ kind: "mcp", name: spans[0][1].trim() });
+    return { targets, via, marker, selfContained: false };
+  }
+
+  for (const span of spans) {
+    const token = span[1].trim();
+    if (span[2]) targets.push({ kind: "agent", name: token });
+    else if (token.startsWith("/")) {
+      targets.push({
+        kind: external ? "external" : "internal",
+        name: token.slice(1).split(/\s+/)[0],
+      });
+    } else if (/^(jarvis|node)\s/.test(token)) targets.push({ kind: "cli", name: token });
+    else if (token.startsWith("mcp__")) targets.push({ kind: "mcp", name: token });
+    // Read, Grep, Glob e texto livre não são chamadas a artefatos: ignorados
+  }
+
+  if (marker && targets.length === 0 && spans[0]) {
+    targets.push({ kind: "unresolved", name: spans[0][1].trim() });
+  }
+  return { targets, via, marker, selfContained: false };
+}
+
+function parseTable(text, title) {
+  const lines = stripFences(text).split("\n");
+  const start = lines.findIndex((l) => l.trim() === `### ${title}`);
+  if (start === -1) return null;
+  const rows = [];
+  let i = start + 1;
+  while (i < lines.length && !lines[i].startsWith("|")) {
+    if (/^#{1,3} /.test(lines[i])) return rows;
+    i++;
+  }
+  i += 2; // cabeçalho e separador
+  for (; i < lines.length && lines[i].startsWith("|"); i++) {
+    const [passo = "", skill = "", condicao = ""] = splitCells(lines[i]);
+    const c = classifyCell(skill);
+    rows.push({
+      passo,
+      condicao,
+      targets: c.targets,
+      via: c.via,
+      marker: c.marker,
+      selfContained: c.selfContained,
+      available: false,
+    });
+  }
+  return rows;
+}
+
+function section(text, title) {
+  const m = text.match(
+    new RegExp(`^## ${title}\\s*\\n([\\s\\S]*?)(?=\\n## |\\n---\\s*\\n|(?![\\s\\S]))`, "m")
+  );
+  return m ? m[1] : null;
+}
+
+function parseAgent(text) {
+  const clean = stripFences(text);
+  const rows = [];
+
+  const skills = section(clean, "Skills Disponíveis");
+  if (skills !== null) {
+    for (const block of skills.split(/^### /m).slice(1)) {
+      const [heading, ...rest] = block.split("\n");
+      // Um bloco pode citar mais de uma skill: uma linha por skill (nome tirado do caminho do SKILL.md).
+      const names = [
+        ...new Set([...block.matchAll(/skills\/([A-Za-z0-9._-]+)\/SKILL\.md/g)].map((m) => m[1])),
+      ];
+      if (names.length === 0) {
+        const token = heading.trim().split(/[\s(]/)[0];
+        if (/[-.]/.test(token)) names.push(token);
+      }
+      const context = rest.map((l) => l.trim()).find((l) => l && !l.startsWith("- ")) ?? "";
+      for (const name of names) {
+        rows.push({
+          passo: null,
+          condicao: context.replace(/:$/, ""),
+          targets: [{ kind: "internal", name }],
+          via: null,
+          marker: null,
+          selfContained: false,
+          available: true,
+        });
+      }
+    }
+  }
+
+  const related = section(clean, "Workflows e Agentes Relacionados");
+  if (related !== null) {
+    for (const line of related.split("\n")) {
+      if (!/^- /.test(line) || /^- Arquivo:/.test(line)) continue;
+      const bold = line.match(/\*\*([^*]+)\*\*/);
+      const code = line.match(/`([^`]+)`/);
+      let name = bold ? bold[1] : code ? code[1] : null;
+      if (!name) continue;
+      if (name.includes("/")) {
+        if (!name.endsWith(".md")) continue;
+        name = name.split("/").pop().replace(/\.md$/, "");
+      }
+      const condicao = line.includes(":") ? line.slice(line.indexOf(":") + 1).trim() : "";
+      rows.push({
+        passo: null,
+        condicao,
+        targets: [{ kind: "internal", name }],
+        via: null,
+        marker: null,
+        selfContained: false,
+        available: false,
+      });
+    }
+  }
+
+  const declared = skills !== null || related !== null;
+  return { declared, selfContained: declared && rows.length === 0, rows };
+}
+
+/**
+ * Lê as chamadas declaradas por um artefato.
+ * @param {"workflow" | "skill" | "agent"} type
+ * @param {string} text
+ * @returns {{ declared: boolean, selfContained: boolean, rows: Row[] }}
+ */
+export function parseDeclaration(type, text) {
+  if (type === "agent") return parseAgent(text);
+  const rows = parseTable(text, type === "workflow" ? WORKFLOW_TITLE : SKILL_TITLE);
+  if (rows === null) return { declared: false, selfContained: false, rows: [] };
+  const hasTargets = rows.some((r) => r.targets.length > 0);
+  return { declared: true, selfContained: rows.some((r) => r.selfContained) && !hasTargets, rows };
+}

package/bin/lib/flow-map/render.js

@@ -0,0 +1,89 @@
+/**
+ * @fileoverview Saída em texto da árvore de chamadas.
+ * @module flow-map/render
+ */
+
+const TYPE_LABEL = {
+  workflow: "workflow",
+  skill: "skill",
+  agent: "agente",
+  cli: "CLI",
+  mcp: "MCP",
+  external: "externo",
+  broken: "?",
+  unresolved: "?",
+};
+
+/**
+ * Resume a coluna `Condição` para uma linha: sem crases, "Se" em minúscula e limite de tamanho.
+ * @param {string} text
+ * @param {number} [max]
+ */
+export function summarizeCondition(text, max = 90) {
+  let t = text.replace(/[`*]/g, "").replace(/\s+/g, " ").trim();
+  if (!t || t === "—") return "";
+  t = t.charAt(0).toLowerCase() + t.slice(1);
+  return t.length > max ? `${t.slice(0, max - 1).trimEnd()}…` : t;
+}
+
+function describe(node) {
+  const head = node.kind === "menu" ? node.name : `${node.name} [${TYPE_LABEL[node.kind]}]`;
+  const notes = [];
+  const condition = summarizeCondition(node.condicao);
+  if (node.available) notes.push("disponível");
+  if (condition) notes.push(condition);
+  if (node.via) notes.push(`via ${node.via}`);
+  if (node.kind === "broken" || node.marker === "quebrada") notes.push("referência quebrada");
+  else if (node.marker === "a confirmar") notes.push("referência a confirmar");
+  if (node.status === "cycle") notes.push("ciclo: já mapeado acima");
+  else if (node.status === "seen") notes.push("já mapeado acima");
+  else if (node.status === "truncated") notes.push("truncado: use --depth N");
+  return notes.length ? `${head}  (${notes.join("; ")})` : head;
+}
+
+/**
+ * @param {import("./tree.js").TreeNode} root
+ * @returns {string[]} linhas da árvore
+ */
+export function renderTree(root) {
+  const lines = [describe(root)];
+  if (root.status === "selfContained") lines.push("└── (autocontido: não chama nenhum outro item)");
+  else if (root.status === "undeclared")
+    lines.push("└── (sem declaração de chamadas: o item não segue a tabela padronizada)");
+
+  function walk(node, prefix) {
+    node.children.forEach((child, i) => {
+      const last = i === node.children.length - 1;
+      lines.push(`${prefix}${last ? "└── " : "├── "}${describe(child)}`);
+      walk(child, `${prefix}${last ? "    " : "│   "}`);
+    });
+  }
+  walk(root, "");
+  return lines;
+}
+
+/**
+ * @param {string} name
+ * @param {string} type
+ * @param {ReturnType<typeof import("./tree.js").reverseEdges>} edges
+ * @returns {string[]}
+ */
+export function renderReverse(name, type, edges) {
+  const lines = [`Quem chama ${name} [${TYPE_LABEL[type]}]`];
+  if (edges.length === 0) {
+    lines.push(`└── nenhum artefato chama ${name} — pode ser um ponto de entrada`);
+    return lines;
+  }
+  edges.forEach((e, i) => {
+    const notes = [];
+    if (e.passo) notes.push(`passo: ${e.passo}`);
+    if (e.available) notes.push("disponível");
+    const condition = summarizeCondition(e.condicao);
+    if (condition) notes.push(condition);
+    if (e.via) notes.push(`via ${e.via}`);
+    lines.push(
+      `${i === edges.length - 1 ? "└── " : "├── "}${e.from} [${TYPE_LABEL[e.type]}]${notes.length ? `  (${notes.join("; ")})` : ""}`
+    );
+  });
+  return lines;
+}

package/bin/lib/flow-map/tree.js

@@ -0,0 +1,248 @@
+/**
+ * @fileoverview Grafo de chamadas e árvore para frente.
+ * @module flow-map/tree
+ */
+
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import { buildIndex } from "./index.js";
+import { parseDeclaration } from "./parse.js";
+
+export const DEFAULT_DEPTH = 4;
+
+/**
+ * Lê o índice e as declarações de todos os artefatos.
+ * @param {string} root - Raiz do framework
+ */
+export function buildGraph(root) {
+  const { items, duplicates } = buildIndex(root);
+  const decl = new Map();
+  for (const item of items.values()) {
+    decl.set(item.name, parseDeclaration(item.type, readFileSync(join(root, item.path), "utf-8")));
+  }
+  return { items, duplicates, decl };
+}
+
+/**
+ * @typedef {Object} TreeNode
+ * @property {string} name
+ * @property {"workflow"|"skill"|"agent"|"cli"|"mcp"|"external"|"broken"|"unresolved"|"menu"} kind
+ * @property {string | null} passo
+ * @property {string} condicao
+ * @property {string | null} via
+ * @property {"quebrada"|"a confirmar"|null} marker
+ * @property {boolean} available
+ * @property {null|"cycle"|"seen"|"truncated"|"undeclared"|"selfContained"} status
+ * @property {TreeNode[]} children
+ */
+
+function hasCalls(graph, name) {
+  const d = graph.decl.get(name);
+  return Boolean(d) && d.rows.some((r) => r.targets.length > 0);
+}
+
+/**
+ * Árvore do que o item chama, até `depth` níveis.
+ * @param {ReturnType<typeof buildGraph>} graph
+ * @param {string} name - Nome de um item do índice
+ * @param {{ depth?: number }} [opts]
+ * @returns {TreeNode}
+ */
+export function forwardTree(graph, name, opts = {}) {
+  const depth = opts.depth ?? DEFAULT_DEPTH;
+  const expanded = new Set([name]);
+
+  function base(partial) {
+    return {
+      passo: null,
+      condicao: "",
+      via: null,
+      marker: null,
+      available: false,
+      status: null,
+      children: [],
+      ...partial,
+    };
+  }
+
+  function childrenOf(itemName, level, ancestors) {
+    const d = graph.decl.get(itemName);
+    const children = [];
+    for (const row of d.rows) {
+      if (row.targets.length === 0) continue;
+      const grouped =
+        row.targets.filter((t) => t.kind === "internal" || t.kind === "agent").length > 1;
+      // Em menu, a condição fica no nó do menu e não se repete em cada alvo.
+      const nodes = row.targets.map((t) =>
+        targetNode(t, grouped ? { ...row, condicao: "", via: null } : row, level + 1, ancestors)
+      );
+      if (grouped) {
+        children.push(
+          base({
+            name: `menu (${nodes.length} opções)`,
+            kind: "menu",
+            passo: row.passo,
+            condicao: row.condicao,
+            via: row.via,
+            children: nodes,
+          })
+        );
+      } else {
+        children.push(...nodes);
+      }
+    }
+    return children;
+  }
+
+  function targetNode(target, row, level, ancestors) {
+    const common = {
+      passo: row.passo,
+      condicao: row.condicao,
+      via: row.via,
+      marker: row.marker,
+      available: row.available,
+    };
+
+    if (["cli", "mcp", "external", "unresolved"].includes(target.kind)) {
+      return base({ name: target.name, kind: target.kind, ...common });
+    }
+    const item = graph.items.get(target.name);
+    if (!item)
+      return base({
+        name: target.name,
+        kind: "broken",
+        ...common,
+        marker: row.marker ?? "quebrada",
+      });
+
+    const node = base({ name: item.name, kind: item.type, ...common });
+    if (ancestors.has(item.name)) node.status = "cycle";
+    else if (expanded.has(item.name)) node.status = "seen";
+    else if (level >= depth) node.status = hasCalls(graph, item.name) ? "truncated" : null;
+    else {
+      expanded.add(item.name);
+      fill(node, level, new Set([...ancestors, item.name]));
+    }
+    return node;
+  }
+
+  function fill(node, level, ancestors) {
+    const d = graph.decl.get(node.name);
+    if (!d.declared) node.status = "undeclared";
+    else if (d.selfContained) node.status = "selfContained";
+    else node.children = childrenOf(node.name, level, ancestors);
+  }
+
+  const item = graph.items.get(name);
+  const root = base({ name, kind: item.type });
+  fill(root, 0, new Set([name]));
+  return root;
+}
+
+function levenshtein(a, b) {
+  const row = Array.from({ length: b.length + 1 }, (_, i) => i);
+  for (let i = 1; i <= a.length; i++) {
+    let prev = row[0];
+    row[0] = i;
+    for (let j = 1; j <= b.length; j++) {
+      const tmp = row[j];
+      row[j] = Math.min(row[j] + 1, row[j - 1] + 1, prev + (a[i - 1] === b[j - 1] ? 0 : 1));
+      prev = tmp;
+    }
+  }
+  return row[b.length];
+}
+
+/**
+ * Até 5 nomes parecidos (prefixo, trecho ou distância de edição de até 1 a cada 4 caracteres).
+ * @param {Map<string, unknown>} items
+ * @param {string} name
+ */
+export function suggest(items, name) {
+  const lower = name.toLowerCase();
+  return [...items.keys()]
+    .map((candidate) => {
+      const c = candidate.toLowerCase();
+      const score =
+        c.startsWith(lower) || lower.startsWith(c)
+          ? 0
+          : c.includes(lower) || lower.includes(c)
+            ? 1
+            : levenshtein(lower, c) <= Math.max(1, Math.floor(Math.min(lower.length, c.length) / 4))
+              ? 2
+              : null;
+      return { candidate, score };
+    })
+    .filter((s) => s.score !== null)
+    .sort((a, b) => a.score - b.score || a.candidate.localeCompare(b.candidate))
+    .slice(0, 5)
+    .map((s) => s.candidate);
+}
+
+/**
+ * Quem declara chamar o item (arestas invertidas do mesmo grafo).
+ * @param {ReturnType<typeof buildGraph>} graph
+ * @param {string} name
+ * @returns {Array<{ from: string, type: string, passo: string | null, condicao: string, via: string | null, available: boolean }>}
+ */
+export function reverseEdges(graph, name) {
+  const edges = [];
+  for (const [from, d] of graph.decl) {
+    if (from === name) continue;
+    for (const row of d.rows) {
+      if (
+        row.targets.some((t) => (t.kind === "internal" || t.kind === "agent") && t.name === name)
+      ) {
+        edges.push({
+          from,
+          type: graph.items.get(from).type,
+          passo: row.passo,
+          condicao: row.condicao,
+          via: row.via,
+          available: row.available,
+        });
+      }
+    }
+  }
+  return edges.sort((a, b) => a.from.localeCompare(b.from));
+}
+
+/**
+ * Confere os nomes citados nas declarações.
+ * - erro: `/nome` ou `nome (agente)` que não existe, e nomes duplicados no índice;
+ * - aviso: linha já marcada "referência quebrada" ou "a confirmar", e artefato sem declaração.
+ * @param {ReturnType<typeof buildGraph>} graph
+ * @returns {{ errors: Array<{ file: string, name: string, reason: string }>, warnings: Array<{ file: string, name: string, reason: string }> }}
+ */
+export function findBrokenReferences(graph) {
+  const errors = duplicatesOf(graph);
+  const warnings = [];
+  for (const [name, d] of graph.decl) {
+    const file = graph.items.get(name).path;
+    if (!d.declared) warnings.push({ file, name, reason: "sem declaração de chamadas" });
+    for (const row of d.rows) {
+      for (const t of row.targets) {
+        if (t.kind === "unresolved") {
+          warnings.push({ file, name: t.name, reason: `referência ${row.marker}` });
+        } else if ((t.kind === "internal" || t.kind === "agent") && !graph.items.has(t.name)) {
+          if (row.marker) warnings.push({ file, name: t.name, reason: `referência ${row.marker}` });
+          else
+            errors.push({
+              file,
+              name: t.name,
+              reason: "não existe como workflow, skill ou agente",
+            });
+        }
+      }
+    }
+  }
+  return { errors, warnings };
+}
+
+function duplicatesOf(graph) {
+  return graph.duplicates.map((name) => ({
+    file: name,
+    name,
+    reason: "nome repetido entre os artefatos",
+  }));
+}

package/bin/lib/tasks/comment.js

@@ -1,3 +1,4 @@
+import { fileURLToPath } from "node:url";
 import { cardUrl } from "../vcs/api.js";
 
 function env(name) {
@@ -13,9 +14,7 @@ async function commentJira(cardKey, message) {
   const token = env("TOKEN_TASK_MANAGER");
   const email = env("USER");
   if (!base || !token) {
-    throw new Error(
-      "Jira: preencha TASK_MANAGER_URL_BASE e TOKEN_TASK_MANAGER no ENV.md",
-    );
+    throw new Error("Jira: preencha TASK_MANAGER_URL_BASE e TOKEN_TASK_MANAGER no ENV.md");
   }
   const auth = email
     ? `Basic ${Buffer.from(`${email}:${token}`).toString("base64")}`
@@ -68,28 +67,24 @@ async function commentLinear(cardKey, message) {
 }
 
 async function commentGithub(cardKey, message) {
-  const token =
-    env("TOKEN_TASK_MANAGER") || env("GITHUB_TOKEN") || env("GH_TOKEN");
+  const token = env("TOKEN_TASK_MANAGER") || env("GITHUB_TOKEN") || env("GH_TOKEN");
   const base = env("TASK_MANAGER_URL_BASE").replace(/\/$/, "");
   if (!token || !base) {
     throw new Error(
-      "GitHub Issues: TASK_MANAGER_URL_BASE (https://github.com/org/repo) e TOKEN_TASK_MANAGER/GITHUB_TOKEN",
+      "GitHub Issues: TASK_MANAGER_URL_BASE (https://github.com/org/repo) e TOKEN_TASK_MANAGER/GITHUB_TOKEN"
     );
   }
   const path = new URL(base).pathname.replace(/^\/+|\/+$/g, "");
   const number = String(cardKey).replace(/^#/, "");
-  const res = await fetch(
-    `https://api.github.com/repos/${path}/issues/${number}/comments`,
-    {
-      method: "POST",
-      headers: {
-        Authorization: `Bearer ${token}`,
-        Accept: "application/vnd.github+json",
-        "Content-Type": "application/json",
-      },
-      body: JSON.stringify({ body: message }),
+  const res = await fetch(`https://api.github.com/repos/${path}/issues/${number}/comments`, {
+    method: "POST",
+    headers: {
+      Authorization: `Bearer ${token}`,
+      Accept: "application/vnd.github+json",
+      "Content-Type": "application/json",
     },
-  );
+    body: JSON.stringify({ body: message }),
+  });
   if (!res.ok) throw new Error(`GitHub ${res.status}: ${await res.text()}`);
 }
 
@@ -107,25 +102,35 @@ async function commentAsana(cardKey, message) {
   if (!res.ok) throw new Error(`Asana ${res.status}: ${await res.text()}`);
 }
 
-const cardKey = process.argv[2];
-const message = process.argv.slice(3).join(" ");
+/**
+ * Comenta num card do task manager configurado em TASK_MANAGER (jira/linear/github/asana).
+ * Usada por `jarvis tasks comment` e pelo skill `eng-global-task-comment`.
+ * @param {string} cardKey - Chave/ID do card (ex: `TASK-123`, ou número de issue no GitHub)
+ * @param {string} message - Texto do comentário
+ */
+export async function runComment(cardKey, message) {
+  if (!cardKey || !message) {
+    console.error("Uso: jarvis tasks comment <TASK_MANAGER_KEY> <mensagem>");
+    process.exit(1);
+  }
+
+  const tm = taskManager();
+  try {
+    if (tm === "linear") await commentLinear(cardKey, message);
+    else if (tm === "github") await commentGithub(cardKey, message);
+    else if (tm === "asana") await commentAsana(cardKey, message);
+    else await commentJira(cardKey, message);
 
-if (!cardKey || !message) {
-  console.error("Uso: comment.js <TASK_MANAGER_KEY> <mensagem>");
-  process.exit(1);
+    const url = cardUrl(tm, env("TASK_MANAGER_URL_BASE"), cardKey);
+    console.log(`💬 Comentário adicionado em ${cardKey} (${tm})`);
+    if (url !== cardKey) console.log(`   ${url}`);
+  } catch (err) {
+    console.error(`⚠️ Não foi possível comentar no card ${cardKey}: ${err.message}`);
+    process.exit(2);
+  }
 }
 
-const tm = taskManager();
-try {
-  if (tm === "linear") await commentLinear(cardKey, message);
-  else if (tm === "github") await commentGithub(cardKey, message);
-  else if (tm === "asana") await commentAsana(cardKey, message);
-  else await commentJira(cardKey, message);
-
-  const url = cardUrl(tm, env("TASK_MANAGER_URL_BASE"), cardKey);
-  console.log(`💬 Comentário adicionado em ${cardKey} (${tm})`);
-  if (url !== cardKey) console.log(`   ${url}`);
-} catch (err) {
-  console.error(`⚠️ Não foi possível comentar no card ${cardKey}: ${err.message}`);
-  process.exit(2);
+// Compatibilidade: continua funcionando como `node bin/lib/tasks/comment.js <key> <mensagem>`
+if (fileURLToPath(import.meta.url) === process.argv[1]) {
+  await runComment(process.argv[2], process.argv.slice(3).join(" "));
 }