htools-htask-gh-issue-sync

name	htools-htask-gh-issue-sync
description	One-way sync of GitHub issues assigned to me into the htask database — creates tasks for new issues, mirrors title/description, marks done on close, archives on unassign. Use when asked to sync issues, sync GitHub tasks, or pull assigned work.

htools-htask-gh-issue-sync

GitHub is the source of truth for issue-sourced tasks; the local db follows. Idempotent — run it as often as you like. The join key is the task's source ref, owner/repo#123.

Gather

GitHub side — raise --limit if the result comes back full; a truncated list must never be read as "everything else got unassigned":

gh search issues --assignee=@me --state=open --limit=200 \
  --json repository,number,title,body,url

The ref for each issue is <repository.nameWithOwner>#<number>.

htask side — live and archived github-sourced tasks:

htask ls --source github --json
htask ls --source github --archived --json

Each object carries everything the sync needs: short_id (what every other htask command takes), title, description, status, and source.ref.

Reconcile

For each assigned open issue:

• No task with its ref → create one. --title takes the issue title literally (token peeling would eat its colons as tags); the bare ref token sets the source. Omit --desc if the body is empty:

  htask add --title <issue title> --desc <issue body> owner/repo#123
  

• Live task with its ref → mirror text: if title or description differ from the issue, htask edit <short_id> --title ... --desc .... Never touch status here — a done task under a still-open issue means the work finished locally before the issue closed; leave it.

• Only an archived task with its ref → it came back after being filed away; there is no unarchive, so create a fresh task as above.

For each live github-sourced task whose ref is not in the assigned-open set, find out why — gh issue view <number> -R <owner/repo> --json state,assignees (or pass the URL if the ref is one) — then:

• closed → htask done <short_id>
• open, but I'm not in the assignees → htask archive <short_id>
• open and still assigned (search lag, transferred repo) → leave it, flag it
• the ref is a PR, not an issue → out of scope, leave it untouched

Hand-made tasks with a github source get the same treatment — that's the point.

Report

End with one compact line per bucket — created / text-updated / done / archived — plus anything odd (transfers, duplicate refs, truncated search). Nothing else.