@k0t0vich/meta-agents-template 0.1.9 → 0.1.10

package/CHANGELOG.md

@@ -2,6 +2,13 @@
 
 All notable changes to this package are documented in this file.
 
+## 0.1.10 - 2026-03-20
+
+### Fixed
+- Implemented GitHub TrackerGateway adapter operations instead of `not implemented` stubs (`CREATE_TASK`, `SET_STATUS`, `ASSIGN_SPRINT`, `COMMIT_BY_NAME`).
+- Added safe `dryRun` support for GitHub tracker operations to validate flows without side effects.
+- Added smoke regression check for `meta:ops CREATE_TASK` (dry-run) to prevent future regressions where command exists but adapter is stubbed.
+
 ## 0.1.9 - 2026-03-20
 
 ### Fixed

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@k0t0vich/meta-agents-template",
-  "version": "0.1.9",
+  "version": "0.1.10",
   "description": "Template system for verification-first agentic development",
   "type": "module",
   "bin": {

package/template/.meta-agents/scripts/tracker/github.mjs

@@ -1,4 +1,549 @@
-export async function createTask() { throw new Error("github adapter: not implemented"); }
-export async function setStatus() { throw new Error("github adapter: not implemented"); }
-export async function commitByName() { throw new Error("github adapter: not implemented"); }
-export async function assignSprint() { throw new Error("github adapter: not implemented"); }
+import { execFileSync } from "node:child_process";
+import process from "node:process";
+
+const STATUS_LABELS = ["TODO", "IN_PROGRESS", "REVIEW", "READY", "BLOCKED", "DONE", "PUBLISH"];
+const STATUS_COLORS = {
+  IN_PROGRESS: "FBCA04",
+  REVIEW: "5319E7",
+  READY: "0E8A16",
+  BLOCKED: "B60205",
+  DONE: "1D76DB",
+  PUBLISH: "0052CC",
+};
+STATUS_COLORS.TODO = "D4C5F9";
+const FALLBACK_COLORS = {
+  type: "C2E0C6",
+  owner: "0E8A16",
+  tracker: "0052CC",
+  sprint: "F9D0C4",
+  default: "BFDADC",
+};
+
+function run(command, args, allowFailure = false) {
+  try {
+    return execFileSync(command, args, {
+      cwd: process.cwd(),
+      encoding: "utf8",
+      stdio: ["ignore", "pipe", "pipe"],
+    }).trim();
+  } catch (error) {
+    if (allowFailure) {
+      return "";
+    }
+    const stderr = String(error?.stderr || "").trim();
+    const stdout = String(error?.stdout || "").trim();
+    throw new Error(`${command} ${args.join(" ")} failed: ${stderr || stdout || error.message}`);
+  }
+}
+
+function readJson(command, args, allowFailure = false) {
+  const raw = run(command, args, allowFailure);
+  if (!raw) {
+    return null;
+  }
+  try {
+    return JSON.parse(raw);
+  } catch (error) {
+    throw new Error(`failed to parse JSON from '${command} ${args.join(" ")}': ${error.message}`);
+  }
+}
+
+function ensureGhReady() {
+  run("gh", ["--version"], false);
+  const auth = run("gh", ["auth", "status"], true);
+  if (!auth) {
+    throw new Error("gh is not authenticated. Run 'gh auth login' first.");
+  }
+}
+
+function toRepoArgs(repo) {
+  if (!repo) {
+    return [];
+  }
+  return ["--repo", String(repo)];
+}
+
+function toNonEmptyString(value) {
+  if (value === null || value === undefined) {
+    return "";
+  }
+  return String(value).trim();
+}
+
+function pickFirstNonEmpty(...values) {
+  for (const value of values) {
+    const normalized = toNonEmptyString(value);
+    if (normalized) {
+      return normalized;
+    }
+  }
+  return "";
+}
+
+function parseIssueNumber(value) {
+  if (typeof value === "number" && Number.isInteger(value) && value > 0) {
+    return String(value);
+  }
+
+  const source = toNonEmptyString(value);
+  if (!source) {
+    return "";
+  }
+
+  const direct = source.match(/^#?(\d+)$/);
+  if (direct) {
+    return direct[1];
+  }
+
+  const issueToken = source.match(/(?:^|[\/\s])issue-(\d+)(?:-|$|\s)/i);
+  if (issueToken) {
+    return issueToken[1];
+  }
+
+  const githubUrl = source.match(/\/issues\/(\d+)(?:$|[/?#])/i);
+  if (githubUrl) {
+    return githubUrl[1];
+  }
+
+  const ref = source.match(/#(\d+)/);
+  if (ref) {
+    return ref[1];
+  }
+
+  return "";
+}
+
+function normalizeStatus(value, fallback = "TODO") {
+  const normalized = toNonEmptyString(value).toUpperCase() || fallback;
+  if (!STATUS_LABELS.includes(normalized)) {
+    throw new Error(
+      `unsupported status '${normalized}'. Allowed: ${STATUS_LABELS.join(", ")}`,
+    );
+  }
+  return normalized;
+}
+
+function normalizeSprintLabel(value) {
+  const sprint = toNonEmptyString(value);
+  if (!sprint) {
+    return "";
+  }
+  if (/^sprint:/i.test(sprint)) {
+    return sprint.replace(/^sprint:/i, "sprint:");
+  }
+  return `sprint:${sprint}`;
+}
+
+function normalizeOwnerLabel(value) {
+  const owner = toNonEmptyString(value);
+  if (!owner) {
+    return "owner:Engineering Agent";
+  }
+  if (/^owner:/i.test(owner)) {
+    return owner.replace(/^owner:/i, "owner:");
+  }
+  return `owner:${owner}`;
+}
+
+function normalizeTypeLabel(value) {
+  const kind = toNonEmptyString(value).toLowerCase() || "task";
+  if (kind.startsWith("type:")) {
+    return kind;
+  }
+  return `type:${kind}`;
+}
+
+function parseLabelsInput(value) {
+  if (!value) {
+    return [];
+  }
+
+  if (Array.isArray(value)) {
+    return value.map((item) => toNonEmptyString(item)).filter(Boolean);
+  }
+
+  return String(value)
+    .split(",")
+    .map((item) => item.trim())
+    .filter(Boolean);
+}
+
+function labelColor(name) {
+  if (STATUS_COLORS[name]) {
+    return STATUS_COLORS[name];
+  }
+
+  const lower = toNonEmptyString(name).toLowerCase();
+  if (lower.startsWith("type:")) {
+    return FALLBACK_COLORS.type;
+  }
+  if (lower.startsWith("owner:")) {
+    return FALLBACK_COLORS.owner;
+  }
+  if (lower.startsWith("tracker:")) {
+    return FALLBACK_COLORS.tracker;
+  }
+  if (lower.startsWith("sprint:")) {
+    return FALLBACK_COLORS.sprint;
+  }
+  return FALLBACK_COLORS.default;
+}
+
+function mergeUnique(values) {
+  return Array.from(new Set(values.map((item) => toNonEmptyString(item)).filter(Boolean)));
+}
+
+function buildCreateTaskLabels(payload) {
+  const status = normalizeStatus(payload.status || "TODO");
+  const labels = [
+    ...parseLabelsInput(payload.labels),
+    status,
+    normalizeTypeLabel(payload.type),
+    normalizeOwnerLabel(payload.owner || payload.ownerRole),
+    "tracker:github",
+  ];
+
+  const sprintLabel = normalizeSprintLabel(payload.sprint);
+  if (sprintLabel) {
+    labels.push(sprintLabel);
+  }
+
+  return mergeUnique(labels);
+}
+
+function renderBulletedValue(value, fallbackText) {
+  const text = toNonEmptyString(value);
+  if (!text) {
+    return `- ${fallbackText}`;
+  }
+  if (text.includes("\n")) {
+    const lines = text
+      .split("\n")
+      .map((line) => line.trim())
+      .filter(Boolean);
+    if (lines.length === 0) {
+      return `- ${fallbackText}`;
+    }
+    return lines.map((line) => `- ${line}`).join("\n");
+  }
+  return `- ${text}`;
+}
+
+function renderCreateTaskBody(payload, labels) {
+  const description = renderBulletedValue(
+    payload.description,
+    "заполнить описание задачи",
+  );
+  const verifiability = renderBulletedValue(
+    payload.verifiability || payload.verification,
+    "strict: TBD; statistical: TBD; human: TBD",
+  );
+  const doneBlock = renderBulletedValue(
+    payload.done,
+    "[ ] Не начато",
+  );
+
+  const metadata = [];
+  metadata.push(`- tracker: github`);
+  metadata.push(`- labels: ${labels.join(", ")}`);
+  const sprintLabel = normalizeSprintLabel(payload.sprint);
+  if (sprintLabel) {
+    metadata.push(`- sprint: ${sprintLabel.replace(/^sprint:/i, "")}`);
+  }
+  const epicRef = parseIssueNumber(payload.epic || payload.linkToEpic || payload.parent);
+  if (epicRef) {
+    metadata.push(`- epic: #${epicRef}`);
+  }
+
+  return [
+    "## PRD Step",
+    "",
+    "### Описание",
+    description,
+    "",
+    "### Проверяемость",
+    verifiability,
+    "",
+    "### Что сделано",
+    doneBlock,
+    "",
+    "## Metadata",
+    ...metadata,
+  ].join("\n");
+}
+
+function ensureLabelExists(name, repo) {
+  const repoArgs = toRepoArgs(repo);
+  const exists = readJson(
+    "gh",
+    ["label", "list", ...repoArgs, "--search", name, "--limit", "100", "--json", "name"],
+    true,
+  );
+
+  if (Array.isArray(exists) && exists.some((item) => item?.name === name)) {
+    return;
+  }
+
+  const color = labelColor(name);
+  const description = "Auto-created by meta:ops github adapter";
+  const created = run(
+    "gh",
+    ["label", "create", name, "--color", color, "--description", description, ...repoArgs],
+    true,
+  );
+
+  if (!created) {
+    const existsAfter = readJson(
+      "gh",
+      ["label", "list", ...repoArgs, "--search", name, "--limit", "100", "--json", "name"],
+      true,
+    );
+    if (!(Array.isArray(existsAfter) && existsAfter.some((item) => item?.name === name))) {
+      throw new Error(`failed to create label '${name}'`);
+    }
+  }
+}
+
+function ensureLabelsExist(labels, repo) {
+  for (const label of labels) {
+    ensureLabelExists(label, repo);
+  }
+}
+
+function resolveTaskIssue(payload) {
+  const issue = parseIssueNumber(payload.task || payload.issue || payload.taskId || payload.id);
+  if (!issue) {
+    throw new Error("missing issue reference in payload (task/issue/taskId/id)");
+  }
+  return issue;
+}
+
+function getIssueLabels(issue, repo) {
+  const repoArgs = toRepoArgs(repo);
+  const issueData = readJson(
+    "gh",
+    ["issue", "view", String(issue), "--json", "labels", ...repoArgs],
+    false,
+  );
+  const labels = issueData?.labels || [];
+  return labels.map((item) => toNonEmptyString(item?.name)).filter(Boolean);
+}
+
+function removeAndAddIssueLabels(issue, repo, labelsToRemove, labelsToAdd) {
+  const repoArgs = toRepoArgs(repo);
+  const args = ["issue", "edit", String(issue), ...repoArgs];
+
+  for (const label of labelsToRemove) {
+    args.push("--remove-label", label);
+  }
+  for (const label of labelsToAdd) {
+    args.push("--add-label", label);
+  }
+
+  run("gh", args, false);
+}
+
+function commentIssue(issue, repo, body) {
+  const content = toNonEmptyString(body);
+  if (!content) {
+    return;
+  }
+  const repoArgs = toRepoArgs(repo);
+  run("gh", ["issue", "comment", String(issue), "--body", content, ...repoArgs], false);
+}
+
+function gitCurrentBranch() {
+  return run("git", ["rev-parse", "--abbrev-ref", "HEAD"], true);
+}
+
+function gitAdd(files) {
+  if (Array.isArray(files) && files.length > 0) {
+    run("git", ["add", ...files.map((item) => String(item))], false);
+    return;
+  }
+  run("git", ["add", "-A"], false);
+}
+
+function ensureStagedChanges() {
+  const staged = run("git", ["diff", "--cached", "--name-only"], true);
+  if (!staged) {
+    throw new Error("no staged changes to commit");
+  }
+}
+
+function buildCommitMessage(payload) {
+  const explicit = pickFirstNonEmpty(payload.message, payload.commitMessage);
+  if (explicit) {
+    return explicit;
+  }
+
+  const issue = parseIssueNumber(payload.task || payload.issue || payload.taskId || payload.id);
+  if (!issue) {
+    throw new Error(
+      "missing commit message. Provide payload.message or payload.issue/task to build '#<issue> <summary>'",
+    );
+  }
+
+  const summary = pickFirstNonEmpty(payload.shortName, payload.title, payload.name, "update");
+  return `#${issue} ${summary}`;
+}
+
+export async function createTask(payload = {}) {
+  const title = pickFirstNonEmpty(payload.shortName, payload.title, payload.name);
+  if (!title) {
+    throw new Error("missing task title (shortName/title/name)");
+  }
+
+  const repo = pickFirstNonEmpty(payload.repo);
+  const labels = buildCreateTaskLabels(payload);
+  const body = renderCreateTaskBody(payload, labels);
+
+  if (payload.dryRun) {
+    console.log(
+      JSON.stringify(
+        {
+          command: "CREATE_TASK",
+          mode: "dry-run",
+          repo: repo || "current",
+          title,
+          labels,
+        },
+        null,
+        2,
+      ),
+    );
+    return;
+  }
+
+  ensureGhReady();
+  ensureLabelsExist(labels, repo);
+
+  const repoArgs = toRepoArgs(repo);
+  const args = ["issue", "create", "--title", title, "--body", body, ...repoArgs];
+  for (const label of labels) {
+    args.push("--label", label);
+  }
+
+  const issueUrl = run("gh", args, false);
+  const issue = parseIssueNumber(issueUrl);
+  const epic = parseIssueNumber(payload.epic || payload.linkToEpic || payload.parent);
+  if (issue && epic) {
+    commentIssue(issue, repo, `Linked to epic #${epic}.`);
+  }
+
+  console.log(`github CREATE_TASK: ${issueUrl}`);
+}
+
+export async function setStatus(payload = {}) {
+  const issue = resolveTaskIssue(payload);
+  const repo = pickFirstNonEmpty(payload.repo);
+  const targetStatus = normalizeStatus(payload.status);
+
+  if (payload.dryRun) {
+    console.log(
+      JSON.stringify(
+        {
+          command: "SET_STATUS",
+          mode: "dry-run",
+          repo: repo || "current",
+          issue,
+          status: targetStatus,
+        },
+        null,
+        2,
+      ),
+    );
+    return;
+  }
+
+  ensureGhReady();
+  ensureLabelsExist([targetStatus], repo);
+
+  const currentLabels = getIssueLabels(issue, repo);
+  const removeStatuses = currentLabels.filter(
+    (label) => STATUS_LABELS.includes(label) && label !== targetStatus,
+  );
+
+  removeAndAddIssueLabels(issue, repo, removeStatuses, [targetStatus]);
+  const reason = pickFirstNonEmpty(payload.reason);
+  if (reason) {
+    commentIssue(issue, repo, `Status -> ${targetStatus}. Reason: ${reason}`);
+  }
+
+  console.log(`github SET_STATUS: #${issue} -> ${targetStatus}`);
+}
+
+export async function commitByName(payload = {}) {
+  const branch = gitCurrentBranch();
+  const expectedBranch = pickFirstNonEmpty(payload.branch);
+  if (expectedBranch && branch && branch !== expectedBranch) {
+    throw new Error(`branch mismatch: current '${branch}', expected '${expectedBranch}'`);
+  }
+
+  const message = buildCommitMessage(payload);
+  const files = Array.isArray(payload.files) ? payload.files : [];
+
+  if (payload.dryRun) {
+    console.log(
+      JSON.stringify(
+        {
+          command: "COMMIT_BY_NAME",
+          mode: "dry-run",
+          branch: branch || "unknown",
+          message,
+          files: files.length > 0 ? files : ["-A"],
+          push: Boolean(payload.push),
+        },
+        null,
+        2,
+      ),
+    );
+    return;
+  }
+
+  gitAdd(files);
+  ensureStagedChanges();
+  run("git", ["commit", "-m", message], false);
+  if (payload.push) {
+    run("git", ["push"], false);
+  }
+
+  console.log(`github COMMIT_BY_NAME: ${message}`);
+}
+
+export async function assignSprint(payload = {}) {
+  const issue = resolveTaskIssue(payload);
+  const repo = pickFirstNonEmpty(payload.repo);
+  const sprintLabel = normalizeSprintLabel(payload.sprint);
+  if (!sprintLabel) {
+    throw new Error("missing sprint in payload");
+  }
+
+  if (payload.dryRun) {
+    console.log(
+      JSON.stringify(
+        {
+          command: "ASSIGN_SPRINT",
+          mode: "dry-run",
+          repo: repo || "current",
+          issue,
+          sprint: sprintLabel,
+        },
+        null,
+        2,
+      ),
+    );
+    return;
+  }
+
+  ensureGhReady();
+  ensureLabelsExist([sprintLabel], repo);
+
+  const currentLabels = getIssueLabels(issue, repo);
+  const removeSprints = currentLabels.filter(
+    (label) => label.toLowerCase().startsWith("sprint:") && label !== sprintLabel,
+  );
+  removeAndAddIssueLabels(issue, repo, removeSprints, [sprintLabel]);
+
+  console.log(`github ASSIGN_SPRINT: #${issue} -> ${sprintLabel}`);
+}