@h-rig/task-sources-plugin 0.0.6-alpha.156

package/dist/src/github-issues-source.js

@@ -0,0 +1,843 @@
+// @bun
+// packages/task-sources-plugin/src/github-issues-source.ts
+import { spawnSync } from "child_process";
+var STATUS_LABELS = new Set(["ready", "blocked", "in-progress", "under-review", "failed", "cancelled"]);
+var RIG_STATUS_COMMENT_MARKER = "<!-- rig:status-comment -->";
+var RIG_METADATA_START = "<!-- rig:metadata:start -->";
+var RIG_METADATA_END = "<!-- rig:metadata:end -->";
+var RIG_STATUS_LABELS = new Set(["rig:running", "rig:pr-open", "rig:ci-fixing", "rig:merging", "rig:done", "rig:needs-attention"]);
+var DEFAULT_GH_TIMEOUT_MS = 15000;
+var DEFAULT_GITHUB_ISSUE_LIST_LIMIT = 1000;
+function statusFor(issue) {
+  const state = (issue.state ?? "").toUpperCase();
+  if (state === "CLOSED")
+    return "closed";
+  const labelNames = labelNamesFor(issue);
+  if (labelNames.includes("in-progress"))
+    return "in_progress";
+  if (labelNames.includes("blocked"))
+    return "blocked";
+  if (labelNames.includes("ready"))
+    return "ready";
+  if (labelNames.includes("under-review"))
+    return "under_review";
+  if (labelNames.includes("failed"))
+    return "failed";
+  if (labelNames.includes("cancelled"))
+    return "cancelled";
+  return "open";
+}
+function parseIssueRefs(raw) {
+  const refs = [...raw.matchAll(/(?:^|[^\w/.-])(?:[\w.-]+\/[\w.-]+#|#)?(\d+)\b/g)].map((match) => match[1]).filter((value) => Boolean(value));
+  return [...new Set(refs)];
+}
+function metadataKeyPattern(keys) {
+  return new RegExp(`^(?:${keys.map((key) => key.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")).join("|")}):\\s*(.*)$`, "i");
+}
+function parseMetadataList(body, keys) {
+  const block = body.match(/<!-- rig:metadata:start -->\s*([\s\S]*?)\s*<!-- rig:metadata:end -->/);
+  if (!block)
+    return [];
+  const lines = block[1].split(/\r?\n/);
+  const values = [];
+  const keyPattern = metadataKeyPattern(keys);
+  for (let index = 0;index < lines.length; index += 1) {
+    const line = lines[index];
+    const sameLine = line.match(keyPattern);
+    if (!sameLine)
+      continue;
+    const inlineValue = sameLine[1]?.trim() ?? "";
+    if (inlineValue) {
+      values.push(...parseIssueRefs(inlineValue));
+      continue;
+    }
+    for (let cursor = index + 1;cursor < lines.length; cursor += 1) {
+      const item = lines[cursor].match(/^\s*-\s*(.+)$/);
+      if (!item)
+        break;
+      values.push(...parseIssueRefs(item[1]));
+    }
+  }
+  return [...new Set(values)];
+}
+function bodyWithoutRigMetadataBlock(body) {
+  return body.replace(/<!-- rig:metadata:start -->\s*[\s\S]*?\s*<!-- rig:metadata:end -->/g, "");
+}
+function parseBodyKeyRefs(body, keys) {
+  const keyPattern = metadataKeyPattern(keys);
+  const values = bodyWithoutRigMetadataBlock(body).split(/\r?\n/).flatMap((line) => {
+    const match = line.match(keyPattern);
+    return match?.[1] ? parseIssueRefs(match[1]) : [];
+  });
+  return [...new Set(values)];
+}
+function parseDeps(body) {
+  const keys = ["depends-on", "deps", "blocked-by", "blocked_by"];
+  return [...new Set([...parseBodyKeyRefs(body, keys), ...parseMetadataList(body, keys)])];
+}
+function parseParents(body) {
+  const keys = ["parents", "parent"];
+  return [...new Set([...parseBodyKeyRefs(body, keys), ...parseMetadataList(body, keys)])];
+}
+function issueTypeFor(issue) {
+  const labels = labelNamesFor(issue);
+  const typed = labels.find((l) => l.startsWith("type:"));
+  if (typed)
+    return typed.slice("type:".length);
+  if (labels.includes("epic"))
+    return "epic";
+  return "task";
+}
+function issueToTask(issue, repo, nativeDependencies) {
+  const labelNames = labelNamesFor(issue);
+  const scope = labelNames.filter((l) => l.startsWith("scope:")).map((l) => l.slice("scope:".length));
+  const roleLabel = labelNames.find((l) => l.startsWith("role:"));
+  const role = roleLabel ? roleLabel.slice("role:".length) : undefined;
+  const validators = labelNames.filter((l) => l.startsWith("validator:")).map((l) => l.slice("validator:".length));
+  const body = issue.body ?? "";
+  const issueNodeId = issue.id ?? issue.nodeId ?? issue.node_id;
+  const parsedDeps = parseDeps(body);
+  const deps = nativeDependencies?.deps ? [...new Set([...parsedDeps, ...nativeDependencies.deps])] : parsedDeps;
+  return {
+    id: String(issue.number),
+    ...typeof issueNodeId === "string" && issueNodeId.trim() ? { issueNodeId: issueNodeId.trim() } : {},
+    deps,
+    status: statusFor(issue),
+    title: issue.title,
+    body,
+    scope,
+    role,
+    validators,
+    url: issue.url ?? issue.html_url,
+    issueType: issueTypeFor(issue),
+    sourceIssueId: `${repo}#${issue.number}`,
+    parentChildDeps: parseParents(body),
+    labels: labelNames,
+    ...nativeDependencies?.degraded ? { nativeDependenciesDegraded: true, nativeDependenciesError: nativeDependencies.degraded } : {},
+    raw: issue
+  };
+}
+function labelNamesFor(issue) {
+  return (issue.labels ?? []).flatMap((label) => {
+    if (typeof label === "string")
+      return [label];
+    return typeof label.name === "string" ? [label.name] : [];
+  });
+}
+function yamlScalar(value) {
+  if (Array.isArray(value)) {
+    return value.length === 0 ? "[]" : `
+${value.map((entry) => `  - ${String(entry)}`).join(`
+`)}`;
+  }
+  if (value && typeof value === "object")
+    return JSON.stringify(value);
+  return String(value);
+}
+function updateRigOwnedMetadataBlock(body, metadata) {
+  const rendered = [
+    RIG_METADATA_START,
+    ...Object.entries(metadata).map(([key, value]) => Array.isArray(value) ? `${key}:${yamlScalar(value)}` : `${key}: ${yamlScalar(value)}`),
+    RIG_METADATA_END
+  ].join(`
+`);
+  const pattern = new RegExp(`${RIG_METADATA_START.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}\\s*[\\s\\S]*?\\s*${RIG_METADATA_END.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}`);
+  if (pattern.test(body))
+    return body.replace(pattern, rendered);
+  return body.trim().length > 0 ? `${body.trimEnd()}
+
+${rendered}
+` : `${rendered}
+`;
+}
+function buildRigStickyStatusComment(input) {
+  const lines = [
+    RIG_STATUS_COMMENT_MARKER,
+    `### Rig status: ${input.status}`,
+    "",
+    input.summary
+  ];
+  if (input.runId)
+    lines.push("", `- Run: ${input.runId}`);
+  if (input.prUrl)
+    lines.push(`- PR: ${input.prUrl}`);
+  for (const detail of input.details ?? [])
+    lines.push(`- ${detail}`);
+  return lines.join(`
+`);
+}
+function isRigStickyStatusComment(body) {
+  return body.includes(RIG_STATUS_COMMENT_MARKER);
+}
+function ghSpawnOptions(extraEnv, timeoutMs) {
+  const env = {
+    ...process.env,
+    ...process.env.GH_TOKEN !== undefined ? { GH_TOKEN: process.env.GH_TOKEN } : {},
+    ...process.env.GITHUB_TOKEN !== undefined ? { GITHUB_TOKEN: process.env.GITHUB_TOKEN } : {},
+    ...process.env.RIG_GITHUB_TOKEN !== undefined ? { RIG_GITHUB_TOKEN: process.env.RIG_GITHUB_TOKEN } : {}
+  };
+  for (const [key, value] of Object.entries(extraEnv ?? {})) {
+    if (value === undefined)
+      delete env[key];
+    else
+      env[key] = value;
+  }
+  return {
+    encoding: "utf-8",
+    timeout: timeoutMs,
+    env
+  };
+}
+function credentialEnv(token) {
+  const clean = token?.trim() ?? "";
+  if (clean)
+    return { GH_TOKEN: clean, GITHUB_TOKEN: clean, RIG_GITHUB_TOKEN: clean };
+  return { GH_TOKEN: undefined, GITHUB_TOKEN: undefined, RIG_GITHUB_TOKEN: undefined };
+}
+async function resolveCredentialEnv(opts, purpose) {
+  if (!opts.credentialProvider)
+    return;
+  const input = {
+    owner: opts.owner,
+    repo: opts.repo,
+    workspaceId: opts.workspaceId ?? `${opts.owner}/${opts.repo}`,
+    ...opts.userId ? { userId: opts.userId } : {},
+    purpose
+  };
+  const resolved = await opts.credentialProvider.resolveGitHubToken(input);
+  return credentialEnv(resolved.token);
+}
+function tokenDiagnostic(value) {
+  const clean = value?.trim() ?? "";
+  return clean ? `present(len=${clean.length})` : "missing";
+}
+function runGh(bin, args, spawn, extraEnv, timeoutMs) {
+  const options = ghSpawnOptions(extraEnv, timeoutMs);
+  const res = spawn(bin, [...args], options);
+  assertGhSuccess(args, res, options.env);
+  if (!res.stdout || res.stdout.trim() === "")
+    return [];
+  return JSON.parse(res.stdout);
+}
+function runGhVoid(bin, args, spawn, extraEnv, timeoutMs) {
+  const options = ghSpawnOptions(extraEnv, timeoutMs);
+  const res = spawn(bin, [...args], options);
+  assertGhSuccess(args, res, options.env);
+}
+function assertGhSuccess(args, res, env) {
+  if (res.error) {
+    const msg = res.error.message ?? String(res.error);
+    throw new Error(`gh CLI not available \u2014 install gh (brew install gh / apt install gh): ${msg}`);
+  }
+  if (res.status !== 0) {
+    throw new Error(`gh ${args.join(" ")} failed (exit ${res.status}): ${res.stderr}
+[rig gh env:standard-plugin] GH_TOKEN=${tokenDiagnostic(env.GH_TOKEN)} GITHUB_TOKEN=${tokenDiagnostic(env.GITHUB_TOKEN)} RIG_GITHUB_TOKEN=${tokenDiagnostic(env.RIG_GITHUB_TOKEN)}`);
+  }
+}
+var DEFAULT_PROJECT_STATUSES = {
+  todo: "Todo",
+  running: "In Progress",
+  prOpen: "In Review",
+  ciFixing: "In Review",
+  merging: "In Review",
+  done: "Done",
+  needsAttention: "Needs Attention"
+};
+function asProjectRecord(value) {
+  return value && typeof value === "object" && !Array.isArray(value) ? value : null;
+}
+function projectString(value) {
+  return typeof value === "string" && value.trim().length > 0 ? value.trim() : null;
+}
+function projectLifecycleStatusForTaskStatus(status) {
+  const normalized = status?.trim().toLowerCase().replace(/[-\s]+/g, "_");
+  switch (normalized) {
+    case "draft":
+    case "open":
+    case "queued":
+    case "ready":
+      return "todo";
+    case "running":
+    case "in_progress":
+      return "running";
+    case "under_review":
+    case "review":
+    case "pr_open":
+      return "prOpen";
+    case "ci_fixing":
+    case "fixing":
+      return "ciFixing";
+    case "merging":
+    case "merge":
+      return "merging";
+    case "closed":
+    case "completed":
+    case "done":
+      return "done";
+    case "blocked":
+    case "cancelled":
+    case "failed":
+    case "needs_attention":
+      return "needsAttention";
+    default:
+      return null;
+  }
+}
+function ghGraphQLFetch(bin, spawnFn, extraEnv, timeoutMs) {
+  return async (query, variables) => {
+    const args = ["api", "graphql", "-f", `query=${query}`];
+    for (const [key, value] of Object.entries(variables)) {
+      if (value === undefined || value === null)
+        continue;
+      args.push("-f", `${key}=${String(value)}`);
+    }
+    const response = runGh(bin, args, spawnFn, extraEnv, timeoutMs);
+    return asProjectRecord(response)?.data ?? response;
+  };
+}
+function issueNodeIdFor(issue) {
+  const id = issue.id ?? issue.nodeId ?? issue.node_id;
+  return typeof id === "string" && id.trim().length > 0 ? id.trim() : null;
+}
+function nativeIssueDependencyRef(value, currentRepo) {
+  const record = asProjectRecord(value);
+  const number = typeof record?.number === "number" ? String(record.number) : projectString(record?.number);
+  if (!number)
+    return null;
+  const repository = asProjectRecord(record?.repository);
+  const owner = projectString(asProjectRecord(repository?.owner)?.login);
+  const name = projectString(repository?.name);
+  if (!owner || !name || `${owner}/${name}` === currentRepo)
+    return number;
+  return `${owner}/${name}#${number}`;
+}
+function nativeDependencyRefsFrom(data, currentRepo) {
+  const issue = asProjectRecord(asProjectRecord(data)?.node);
+  const blockedBy = asProjectRecord(issue?.blockedBy);
+  const nodes = Array.isArray(blockedBy?.nodes) ? blockedBy.nodes : [];
+  return [...new Set(nodes.flatMap((node) => {
+    const ref = nativeIssueDependencyRef(node, currentRepo);
+    return ref ? [ref] : [];
+  }))];
+}
+async function readNativeDependenciesForIssue(input) {
+  const issueId = issueNodeIdFor(input.issue);
+  if (!issueId)
+    return { deps: [], degraded: "GitHub issue node id is unavailable." };
+  const query = `
+    query RigIssueNativeDependencies($issueId: ID!) {
+      node(id: $issueId) {
+        ... on Issue {
+          blockedBy(first: 100) {
+            nodes {
+              number
+              repository { name owner { login } }
+            }
+          }
+        }
+      }
+    }
+  `;
+  try {
+    return {
+      deps: nativeDependencyRefsFrom(await input.fetchGraphQL(query, { issueId }, "gh-cli"), input.repo)
+    };
+  } catch (error) {
+    const detail = error instanceof Error ? error.message : String(error);
+    return { deps: [], degraded: detail };
+  }
+}
+function formatIssueReference(ref) {
+  const clean = ref.trim().replace(/^#/, "");
+  return /^\d+$/.test(clean) ? `#${clean}` : clean;
+}
+function appendReferenceLines(body, deps, parents) {
+  const lines = [];
+  const cleanDeps = (deps ?? []).map(formatIssueReference).filter((ref) => ref.length > 0);
+  const cleanParents = (parents ?? []).map(formatIssueReference).filter((ref) => ref.length > 0);
+  if (cleanDeps.length > 0)
+    lines.push(`depends-on: ${cleanDeps.join(", ")}`);
+  if (cleanParents.length > 0)
+    lines.push(`parents: ${cleanParents.join(", ")}`);
+  if (lines.length === 0)
+    return body;
+  return body.trim().length > 0 ? `${body.trimEnd()}
+
+${lines.join(`
+`)}` : lines.join(`
+`);
+}
+function bodyForCreatedTask(input) {
+  const metadata = { ...input.metadata ?? {} };
+  if (input.deps && input.deps.length > 0)
+    metadata["depends-on"] = input.deps.map(formatIssueReference);
+  if (input.parents && input.parents.length > 0)
+    metadata.parents = input.parents.map(formatIssueReference);
+  return updateRigOwnedMetadataBlock(appendReferenceLines(input.body, input.deps, input.parents), metadata);
+}
+function projectStatusFieldFrom(data, projectId) {
+  const fields = asProjectRecord(asProjectRecord(asProjectRecord(data)?.node)?.fields)?.nodes;
+  for (const node of Array.isArray(fields) ? fields : []) {
+    const record = asProjectRecord(node);
+    if (projectString(record?.name)?.toLowerCase() !== "status")
+      continue;
+    const id = projectString(record?.id);
+    if (!id)
+      continue;
+    const options = Array.isArray(record?.options) ? record.options.flatMap((option) => {
+      const optionRecord = asProjectRecord(option);
+      const optionId = projectString(optionRecord?.id);
+      const name = projectString(optionRecord?.name);
+      return optionId && name ? [{ id: optionId, name }] : [];
+    }) : [];
+    return { id, name: "Status", options };
+  }
+  throw new Error(`GitHub Project ${projectId} does not expose a Status single-select field.`);
+}
+async function resolveProjectStatusField(input) {
+  const query = `
+    query RigProjectStatusField($projectId: ID!) {
+      node(id: $projectId) {
+        ... on ProjectV2 {
+          fields(first: 50) {
+            nodes {
+              ... on ProjectV2FieldCommon { id name }
+              ... on ProjectV2SingleSelectField { id name options { id name } }
+            }
+          }
+        }
+      }
+    }
+  `;
+  return projectStatusFieldFrom(await input.fetchGraphQL(query, { projectId: input.projectId }, input.token), input.projectId);
+}
+async function ensureIssueProjectItem(input) {
+  const query = `
+    query RigFindProjectIssueItem($projectId: ID!) {
+      node(id: $projectId) {
+        ... on ProjectV2 {
+          items(first: 100) { nodes { id content { ... on Issue { id } } } }
+        }
+      }
+    }
+  `;
+  const data = await input.fetchGraphQL(query, { projectId: input.projectId }, input.token);
+  const nodes = asProjectRecord(asProjectRecord(asProjectRecord(data)?.node)?.items)?.nodes;
+  for (const node of Array.isArray(nodes) ? nodes : []) {
+    const record = asProjectRecord(node);
+    const content = asProjectRecord(record?.content);
+    if (projectString(content?.id) === input.issueNodeId) {
+      const id2 = projectString(record?.id);
+      if (id2)
+        return { id: id2, created: false };
+    }
+  }
+  const mutation = `
+    mutation RigAddIssueToProject($projectId: ID!, $contentId: ID!) {
+      addProjectV2ItemById(input: { projectId: $projectId, contentId: $contentId }) { item { id } }
+    }
+  `;
+  const created = await input.fetchGraphQL(mutation, { projectId: input.projectId, contentId: input.issueNodeId }, input.token);
+  const addResult = asProjectRecord(asProjectRecord(created)?.addProjectV2ItemById);
+  const id = projectString(asProjectRecord(addResult?.item)?.id);
+  if (!id)
+    throw new Error("GitHub Project item creation did not return an item id.");
+  return { id, created: true };
+}
+async function updateIssueProjectStatus(input) {
+  const mutation = `
+    mutation RigUpdateProjectStatus($projectId: ID!, $itemId: ID!, $fieldId: ID!, $optionId: String!) {
+      updateProjectV2ItemFieldValue(input: {
+        projectId: $projectId,
+        itemId: $itemId,
+        fieldId: $fieldId,
+        value: { singleSelectOptionId: $optionId }
+      }) { projectV2Item { id } }
+    }
+  `;
+  await input.fetchGraphQL(mutation, {
+    projectId: input.projectId,
+    itemId: input.itemId,
+    fieldId: input.fieldId,
+    optionId: input.optionId
+  }, input.token);
+}
+function fetchIssueNodeId(bin, repo, spawnFn, id, extraEnv, timeoutMs) {
+  const issue = runGh(bin, ["issue", "view", String(id), "--repo", repo, "--json", "id"], spawnFn, extraEnv, timeoutMs);
+  return projectString(issue.id) ?? projectString(issue.nodeId) ?? projectString(issue.node_id);
+}
+async function syncGitHubProjectStatus(bin, repo, spawnFn, id, status, projects, extraEnv, timeoutMs) {
+  if (!projects?.enabled)
+    return;
+  const projectId = projectString(projects.projectId);
+  if (!projectId)
+    throw new Error("GitHub Projects status sync is enabled but projectId is missing.");
+  const lifecycleStatus = projectLifecycleStatusForTaskStatus(status);
+  if (!lifecycleStatus)
+    return;
+  const issueNodeId = fetchIssueNodeId(bin, repo, spawnFn, id, extraEnv, timeoutMs);
+  if (!issueNodeId)
+    throw new Error(`GitHub issue ${repo}#${id} did not expose a node id for Projects status sync.`);
+  const projectStatus = projectString(projects.statuses?.[lifecycleStatus]) ?? DEFAULT_PROJECT_STATUSES[lifecycleStatus];
+  const fetchGraphQL = ghGraphQLFetch(bin, spawnFn, extraEnv, timeoutMs);
+  const field = await resolveProjectStatusField({ projectId, token: "gh-cli", fetchGraphQL });
+  const option = field.options.find((candidate) => candidate.name.toLowerCase() === projectStatus.toLowerCase() || candidate.id === projectStatus);
+  if (!option)
+    throw new Error(`GitHub Project ${projectId} Status field does not contain option "${projectStatus}".`);
+  const item = await ensureIssueProjectItem({ projectId, issueNodeId, token: "gh-cli", fetchGraphQL });
+  await updateIssueProjectStatus({
+    projectId,
+    itemId: item.id,
+    fieldId: projectString(projects.statusFieldId) ?? field.id,
+    optionId: option.id,
+    token: "gh-cli",
+    fetchGraphQL
+  });
+}
+var TERMINAL_TASK_STATUSES = new Set(["closed", "completed", "merged", "cancelled", "resolved", "done"]);
+function normalizeTaskStatusToken(status) {
+  return status?.trim().toLowerCase().replace(/[-\s]+/g, "_") ?? "";
+}
+function issueUpdatesMode(value) {
+  return value === "off" || value === "minimal" || value === "lifecycle" ? value : "lifecycle";
+}
+function isTerminalTaskStatus(status) {
+  return TERMINAL_TASK_STATUSES.has(normalizeTaskStatusToken(status));
+}
+function shouldWriteIssueUpdate(mode, status) {
+  if (mode === "off")
+    return false;
+  if (mode === "lifecycle")
+    return true;
+  return isTerminalTaskStatus(status);
+}
+function isRunningStatus(status) {
+  return normalizeTaskStatusToken(status) === "running";
+}
+function assignRunningIssue(bin, repo, spawnFn, id, assignee, extraEnv, timeoutMs) {
+  runGhVoid(bin, ["issue", "edit", String(id), "--repo", repo, "--add-assignee", assignee?.trim() || "@me"], spawnFn, extraEnv, timeoutMs);
+}
+function statusLabelFor(status) {
+  switch (status) {
+    case "running":
+    case "in_progress":
+      return "in-progress";
+    case "blocked":
+      return "blocked";
+    case "ready":
+      return "ready";
+    case "under_review":
+      return "under-review";
+    case "failed":
+      return "failed";
+    case "cancelled":
+      return "cancelled";
+    case "ci_fixing":
+      return "under-review";
+    case "merging":
+      return "under-review";
+    case "needs_attention":
+      return "blocked";
+    case "closed":
+    case "completed":
+    case "open":
+      return null;
+    default:
+      throw new Error(`unsupported status: ${status}`);
+  }
+}
+function rigStatusLabelFor(status) {
+  switch (status) {
+    case "running":
+    case "in_progress":
+      return "rig:running";
+    case "under_review":
+      return "rig:pr-open";
+    case "closed":
+    case "completed":
+      return "rig:done";
+    case "ci_fixing":
+      return "rig:ci-fixing";
+    case "merging":
+      return "rig:merging";
+    case "needs_attention":
+    case "failed":
+    case "blocked":
+      return "rig:needs-attention";
+    case "ready":
+    case "cancelled":
+    case "open":
+      return null;
+    default:
+      return null;
+  }
+}
+async function applyIssueStatus(bin, repo, spawnFn, id, status, projects, runningAssignee, issueUpdates, extraEnv, timeoutMs) {
+  const targetLabel = status === "closed" || status === "completed" ? null : statusLabelFor(status);
+  const targetRigLabel = rigStatusLabelFor(status);
+  const shouldSyncLifecycle = shouldWriteIssueUpdate(issueUpdates, status);
+  for (const l of [...STATUS_LABELS, ...RIG_STATUS_LABELS]) {
+    if (targetLabel !== null && l === targetLabel)
+      continue;
+    if (targetRigLabel !== null && l === targetRigLabel)
+      continue;
+    try {
+      runGhVoid(bin, ["issue", "edit", String(id), "--repo", repo, "--remove-label", l], spawnFn, extraEnv, timeoutMs);
+    } catch {}
+  }
+  for (const label of [targetLabel, targetRigLabel].filter((value) => Boolean(value))) {
+    try {
+      runGhVoid(bin, ["issue", "edit", String(id), "--repo", repo, "--add-label", label], spawnFn, extraEnv, timeoutMs);
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      if (!/not found/i.test(message)) {
+        throw error;
+      }
+      ensureStatusLabel(bin, repo, spawnFn, label, extraEnv, timeoutMs);
+      runGhVoid(bin, ["issue", "edit", String(id), "--repo", repo, "--add-label", label], spawnFn, extraEnv, timeoutMs);
+    }
+  }
+  if (isRunningStatus(status)) {
+    assignRunningIssue(bin, repo, spawnFn, id, runningAssignee, extraEnv, timeoutMs);
+    if (shouldSyncLifecycle) {
+      upsertRigStickyComment(bin, repo, spawnFn, String(id), buildRigStickyStatusComment({
+        status: "running",
+        summary: "Rig run started."
+      }), extraEnv, timeoutMs);
+    }
+  }
+  if (shouldSyncLifecycle) {
+    await syncGitHubProjectStatus(bin, repo, spawnFn, id, status, projects, extraEnv, timeoutMs);
+  }
+  if (status === "closed" || status === "completed") {
+    runGhVoid(bin, ["issue", "close", String(id), "--repo", repo], spawnFn, extraEnv, timeoutMs);
+  }
+}
+function ensureStatusLabel(bin, repo, spawnFn, label, extraEnv, timeoutMs) {
+  try {
+    runGhVoid(bin, [
+      "label",
+      "create",
+      label,
+      "--repo",
+      repo,
+      "--color",
+      "6f42c1",
+      "--description",
+      "Task status managed by Rig"
+    ], spawnFn, extraEnv, timeoutMs);
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    if (!/already exists/i.test(message)) {
+      throw error;
+    }
+  }
+}
+function upsertRigStickyComment(bin, repo, spawnFn, id, body, extraEnv, timeoutMs) {
+  const comments = runGh(bin, ["api", `repos/${repo}/issues/${id}/comments`, "--paginate"], spawnFn, extraEnv, timeoutMs);
+  const existing = comments.find((comment) => typeof comment.body === "string" && comment.body.includes(RIG_STATUS_COMMENT_MARKER));
+  if (existing) {
+    runGhVoid(bin, ["api", "-X", "PATCH", `repos/${repo}/issues/comments/${existing.id}`, "-f", `body=${body}`], spawnFn, extraEnv, timeoutMs);
+    return;
+  }
+  runGhVoid(bin, ["api", "-X", "POST", `repos/${repo}/issues/${id}/comments`, "-f", `body=${body}`], spawnFn, extraEnv, timeoutMs);
+}
+function notifyTaskChanged(onTaskChanged, repo, id, status) {
+  onTaskChanged?.({ repo, id, ...status ? { status } : {}, reason: "github-issue-updated" });
+}
+function fetchIssueBody(bin, repo, spawnFn, id, extraEnv, timeoutMs) {
+  const issue = runGh(bin, [
+    "issue",
+    "view",
+    String(id),
+    "--repo",
+    repo,
+    "--json",
+    "body"
+  ], spawnFn, extraEnv, timeoutMs);
+  return typeof issue.body === "string" ? issue.body : undefined;
+}
+function applyLabels(bin, repo, spawnFn, id, labels, action, extraEnv, timeoutMs) {
+  for (const rawLabel of labels) {
+    const label = rawLabel.trim();
+    if (!label)
+      continue;
+    if (action === "--add-label") {
+      try {
+        runGhVoid(bin, ["issue", "edit", String(id), "--repo", repo, action, label], spawnFn, extraEnv, timeoutMs);
+      } catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        if (!/not found/i.test(message))
+          throw error;
+        ensureStatusLabel(bin, repo, spawnFn, label, extraEnv, timeoutMs);
+        runGhVoid(bin, ["issue", "edit", String(id), "--repo", repo, action, label], spawnFn, extraEnv, timeoutMs);
+      }
+      continue;
+    }
+    try {
+      runGhVoid(bin, ["issue", "edit", String(id), "--repo", repo, action, label], spawnFn, extraEnv, timeoutMs);
+    } catch {}
+  }
+}
+async function applyIssueUpdate(bin, repo, spawnFn, id, update, projects, runningAssignee, issueUpdates, extraEnv, timeoutMs) {
+  if (update.status) {
+    await applyIssueStatus(bin, repo, spawnFn, id, update.status, projects, runningAssignee, issueUpdates, extraEnv, timeoutMs);
+  }
+  if (update.comment?.trim() && shouldWriteIssueUpdate(issueUpdates, update.status)) {
+    if (isRigStickyStatusComment(update.comment)) {
+      upsertRigStickyComment(bin, repo, spawnFn, String(id), update.comment, extraEnv, timeoutMs);
+    } else {
+      runGhVoid(bin, ["issue", "comment", String(id), "--repo", repo, "--body", update.comment], spawnFn, extraEnv, timeoutMs);
+    }
+  }
+  const editArgs = ["issue", "edit", String(id), "--repo", repo];
+  if (update.title?.trim()) {
+    editArgs.push("--title", update.title.trim());
+  }
+  const nextBody = update.metadata ? updateRigOwnedMetadataBlock(update.body ?? fetchIssueBody(bin, repo, spawnFn, id, extraEnv, timeoutMs) ?? "", update.metadata) : update.body;
+  if (nextBody !== undefined) {
+    editArgs.push("--body", nextBody);
+  }
+  if (editArgs.length > 5) {
+    runGhVoid(bin, editArgs, spawnFn, extraEnv, timeoutMs);
+  }
+}
+function createGitHubIssuesTaskSource(opts) {
+  const bin = opts.ghBinary ?? "gh";
+  const state = opts.state ?? "open";
+  const repo = `${opts.owner}/${opts.repo}`;
+  const spawnFn = opts.spawn ?? spawnSync;
+  const timeoutMs = Math.max(1000, Math.trunc(opts.timeoutMs ?? DEFAULT_GH_TIMEOUT_MS));
+  const listLimit = Math.max(1, Math.trunc(opts.listLimit ?? DEFAULT_GITHUB_ISSUE_LIST_LIMIT));
+  const issueUpdates = issueUpdatesMode(opts.issueUpdates);
+  async function issueToTaskWithOptionalNativeDependencies(issue, env) {
+    if (!opts.useNativeDependencies)
+      return issueToTask(issue, repo);
+    const nativeDependencies = await readNativeDependenciesForIssue({
+      issue,
+      repo,
+      fetchGraphQL: ghGraphQLFetch(bin, spawnFn, env, timeoutMs)
+    });
+    return issueToTask(issue, repo, nativeDependencies);
+  }
+  return {
+    id: "std:github-issues",
+    kind: "github-issues",
+    async list() {
+      const labelArg = opts.labels && opts.labels.length > 0 ? ["--label", opts.labels.join(",")] : [];
+      const assigneeArg = opts.assignee?.trim() ? ["--assignee", opts.assignee.trim()] : [];
+      const args = [
+        "issue",
+        "list",
+        "--repo",
+        repo,
+        ...labelArg,
+        ...assigneeArg,
+        "--state",
+        state,
+        "--limit",
+        String(listLimit),
+        "--json",
+        "number,title,body,labels,state,url,assignees,id"
+      ];
+      const env = await resolveCredentialEnv(opts, "selected-repo");
+      const rawIssues = runGh(bin, args, spawnFn, env, timeoutMs);
+      if (rawIssues.length >= listLimit) {
+        throw new Error(`GitHub issue list for ${repo} reached the configured limit (${listLimit}); refusing to silently truncate matching issues. Increase taskSource.options.listLimit or narrow labels/state/assignee.`);
+      }
+      const issues = rawIssues.filter((issue) => !issue.pull_request);
+      return Promise.all(issues.map((issue) => issueToTaskWithOptionalNativeDependencies(issue, env)));
+    },
+    async get(id) {
+      const env = await resolveCredentialEnv(opts, "selected-repo");
+      let issue;
+      try {
+        issue = runGh(bin, [
+          "issue",
+          "view",
+          String(id),
+          "--repo",
+          repo,
+          "--json",
+          "number,title,body,labels,state,url,assignees,id"
+        ], spawnFn, env, timeoutMs);
+      } catch (error) {
+        const detail = error instanceof Error ? error.message : String(error);
+        if (/could not resolve to (an? )?(issue|pullrequest)|no issues? (found|matched)|404 not found|gh: not found|gh issue view\b[\s\S]*failed \(exit \d+\): not found\b/i.test(detail)) {
+          return;
+        }
+        throw new Error(`Failed to read task ${id} from GitHub repo ${repo}: ${detail}`);
+      }
+      return issueToTaskWithOptionalNativeDependencies(issue, env);
+    },
+    async updateStatus(id, status) {
+      const env = await resolveCredentialEnv(opts, "selected-repo");
+      await applyIssueStatus(bin, repo, spawnFn, id, status, opts.projects, opts.assignee, issueUpdates, env, timeoutMs);
+      notifyTaskChanged(opts.onTaskChanged, repo, id, status);
+    },
+    async updateTask(id, update) {
+      const env = await resolveCredentialEnv(opts, "selected-repo");
+      await applyIssueUpdate(bin, repo, spawnFn, id, update, opts.projects, opts.assignee, issueUpdates, env, timeoutMs);
+      notifyTaskChanged(opts.onTaskChanged, repo, id, update.status);
+    },
+    async addLabels(id, labels) {
+      const env = await resolveCredentialEnv(opts, "selected-repo");
+      applyLabels(bin, repo, spawnFn, id, labels, "--add-label", env, timeoutMs);
+      notifyTaskChanged(opts.onTaskChanged, repo, id);
+    },
+    async removeLabels(id, labels) {
+      const env = await resolveCredentialEnv(opts, "selected-repo");
+      applyLabels(bin, repo, spawnFn, id, labels, "--remove-label", env, timeoutMs);
+      notifyTaskChanged(opts.onTaskChanged, repo, id);
+    },
+    async createIssue(input) {
+      const env = await resolveCredentialEnv(opts, "selected-repo");
+      const body = input.body ?? "";
+      const args = [
+        "api",
+        "-X",
+        "POST",
+        `repos/${repo}/issues`,
+        "-f",
+        `title=${input.title}`,
+        "-f",
+        `body=${body}`,
+        ...(input.labels ?? []).flatMap((label) => ["-f", `labels[]=${label}`])
+      ];
+      const issue = runGh(bin, args, spawnFn, env, timeoutMs);
+      notifyTaskChanged(opts.onTaskChanged, repo, String(issue.number));
+      return issueToTask({ ...issue, body: issue.body ?? body }, repo);
+    },
+    async create(input) {
+      const env = await resolveCredentialEnv(opts, "selected-repo");
+      const body = bodyForCreatedTask(input);
+      const args = [
+        "api",
+        "-X",
+        "POST",
+        `repos/${repo}/issues`,
+        "-f",
+        `title=${input.title}`,
+        "-f",
+        `body=${body}`,
+        "-f",
+        "labels[]=rig:generated"
+      ];
+      const issue = runGh(bin, args, spawnFn, env, timeoutMs);
+      notifyTaskChanged(opts.onTaskChanged, repo, String(issue.number));
+      return issueToTask({ ...issue, body: issue.body ?? body }, repo);
+    },
+    async getIssueBody(id) {
+      const env = await resolveCredentialEnv(opts, "selected-repo");
+      return fetchIssueBody(bin, repo, spawnFn, id, env, timeoutMs);
+    }
+  };
+}
+export {
+  updateRigOwnedMetadataBlock,
+  createGitHubIssuesTaskSource,
+  buildRigStickyStatusComment,
+  RIG_STATUS_COMMENT_MARKER,
+  RIG_METADATA_START,
+  RIG_METADATA_END
+};