@volter/twin-github 0.1.0 → 0.1.1

package/src/github-mirror-state.ts

@@ -0,0 +1,369 @@
+// GitHub MIRROR STATE — the ONE named store the mirror console renders (runtime contract
+// R5, the store door; R3, mirror purity): `GET /twin/store/mirror`, declared on the pack's
+// own fetch adapter (`github-server.ts`) and served from it. A deterministic projection of
+// the stored state — pull requests grouped by repo (the per-repo selector), issues,
+// reviews/comments, Actions, releases, discussions, contents, notifications, deployments,
+// projects, insights and settings — built from the twin's own evidence + local-write state.
+// No wall-clock, no randomness: the same stored state projects the same bytes. Server-side
+// only — the mirror module (`github-mirror-ui.ts`) never imports this; it reads the door
+// over the wire. The git plane (bare repos, smart-HTTP) is never read here: the projection
+// is over the folded REST state alone.
+//
+// Honesty: the github world is an EVIDENCE mirror — observed data carries PR metadata +
+// review/comment COUNTS but not their content; local simulator/fork writes carry
+// titles/bodies. So review/comment timeline entries are surfaced from the observed counts
+// and labelled as such; PR titles/bodies appear when present.
+import { discussionCategoriesFor, githubState } from './github-twin.ts';
+import { GITHUB_WEB_ORIGIN, githubIssuePath, githubPullPath } from './github-shared.ts';
+
+const OBSERVED = 'content not mirrored by the evidence twin';
+
+/** The `mirror` store: the whole console payload, projected from the twin's github world. */
+export function githubMirrorState(root?: string): Record<string, unknown> {
+  const { prs, issues, reviews: foldedReviews, comments: foldedComments, statuses, checkRuns, milestones, workflows: foldedWorkflows, workflowRuns, jobs, releases: foldedReleases, releaseAssets, tags, discussions: foldedDiscussions, discussionComments: foldedDiscussionComments, discussionCategories: customCategories, contents: foldedContents, notifications: foldedNotifications, deployments: foldedDeployments, deploymentStatuses: foldedDeploymentStatuses, environments: foldedEnvironments, projects: foldedProjects, projectFields: foldedProjectFields, projectItems: foldedProjectItems, projectViews: foldedProjectViews, repos: foldedRepos, collaborators: foldedCollaborators, webhooks: foldedWebhooks, branches: foldedBranches } = githubState(root);
+  // CI rollup per PR head_sha from commit statuses + check runs (a LOCAL CI construct;
+  // observed-only PRs carry no head_sha CI, so this stays null for them — honesty).
+  // Precedence mirrors GitHub's rollup: any failure/error → 'failure'; any pending/queued/
+  // in_progress → 'pending'; all success/neutral → 'success'.
+  const ciStatusFor = (repository: string, headSha?: string): string | undefined => {
+    if (!headSha) return undefined;
+    const relStatuses = statuses.filter((s) => s.repository === repository && s.sha === headSha);
+    const relChecks = checkRuns.filter((c) => c.repository === repository && c.head_sha === headSha);
+    if (!relStatuses.length && !relChecks.length) return undefined;
+    const states: string[] = [
+      ...relStatuses.map((s) => s.state),
+      ...relChecks.map((c) => (c.status === 'completed' ? (c.conclusion ?? 'neutral') : 'pending')),
+    ];
+    if (states.some((s) => s === 'failure' || s === 'error')) return 'failure';
+    if (states.some((s) => s === 'pending')) return 'pending';
+    return 'success';
+  };
+  const pullRequests = prs.map((pr) => {
+    // A PR's merge state: an explicit merged write wins; otherwise the recorded state,
+    // defaulting to open. We never fabricate a title for observed-only PRs.
+    const state = pr.merged ? 'merged' : (pr.state ?? 'open');
+    // milestone: a local PATCH stores the NUMBER; surface its title from state.milestones.
+    const ms = pr.milestone !== undefined ? milestones.find((m) => m.repository === pr.repository && m.number === pr.milestone) : undefined;
+    return {
+      repo: pr.repository,
+      number: pr.number,
+      title: pr.title,
+      body: pr.body,
+      state,
+      merged: pr.merged ?? false,
+      mergedAt: pr.merged_at,
+      mergeCommit: pr.merge_commit_sha,
+      url: `${GITHUB_WEB_ORIGIN}${githubPullPath(pr.repository, pr.number)}`,
+      baseBranch: pr.base_ref,
+      headSha: pr.head_sha,
+      changedFiles: pr.changed_files,
+      commitsCount: pr.commits,
+      commentsCount: pr.comment_count,
+      reviewCount: pr.review_count,
+      reviewCommentsCount: foldedComments.filter((c) => c.repository === pr.repository && c.number === pr.number && c.kind === 'review').length,
+      labels: (pr.labels ?? []).map((name) => ({ name })),
+      assignees: pr.assignees ?? [],
+      // requested reviewers (LOCAL writes): bare logins distinct from submitted reviews.
+      requestedReviewers: pr.requested_reviewers ?? [],
+      // milestone title (LOCAL write); undefined for observed-only PRs.
+      milestone: ms?.title,
+      // additions/deletions line counts: roll up from a carried file list on LOCAL writes;
+      // undefined for observed-only PRs (the evidence fold never carries line counts).
+      additions: pr.additions,
+      deletions: pr.deletions,
+      // CI rollup over head_sha statuses + check-runs; undefined when no CI evidence.
+      ciStatus: ciStatusFor(pr.repository, pr.head_sha),
+    };
+  });
+  // Per-commit detail + per-file diffs ride on LOCAL PR writes only (observed PR evidence
+  // carries COUNTS, never content) — so these lists are empty for observed-only PRs, keeping
+  // the mirror honest. Each entry is tagged with repo+number so the client can scope it to
+  // the selected PR, mirroring the GitHub conversation's Commits + Files-changed sections.
+  const commits = prs.flatMap((pr) =>
+    (pr.commits_list ?? []).map((c) => ({
+      repo: pr.repository,
+      number: pr.number,
+      sha: c.sha,
+      message: c.message,
+      author: c.author_name,
+      date: c.author_date,
+      url: `${GITHUB_WEB_ORIGIN}/${pr.repository}/commit/${c.sha}`,
+    })),
+  );
+  const files = prs.flatMap((pr) =>
+    (pr.files ?? []).map((f) => ({
+      repo: pr.repository,
+      number: pr.number,
+      filename: f.filename,
+      status: f.status,
+      additions: f.additions,
+      deletions: f.deletions,
+      changes: f.changes,
+      // patch: the unified-diff hunk text (LOCAL writes only) — the Files-changed diff view
+      // renders these as +/- lines; observed PRs carry no per-file diff so this is undefined.
+      patch: f.patch,
+    })),
+  );
+  // First-class issues (a LOCAL construct) grouped per repo via the `repo` field, like PRs.
+  const issuesOut = issues.map((iss) => {
+    const ms = iss.milestone !== undefined ? milestones.find((m) => m.repository === iss.repository && m.number === iss.milestone) : undefined;
+    return {
+      repo: iss.repository,
+      number: iss.number,
+      title: iss.title,
+      body: iss.body,
+      state: iss.state ?? 'open',
+      url: `${GITHUB_WEB_ORIGIN}${githubIssuePath(iss.repository, iss.number)}`,
+      createdAt: iss.created_at,
+      updatedAt: iss.updated_at,
+      labels: (iss.labels ?? []).map((name) => ({ name })),
+      assignees: iss.assignees ?? [],
+      milestone: ms?.title,
+      stateReason: iss.state_reason ?? undefined,
+      locked: iss.locked ?? false,
+      // linked PRs/issues (a LOCAL relation): surface as typed references the client links.
+      linked: (iss.linked ?? []).map((l) => ({
+        type: l.type,
+        number: l.number,
+        url: l.type === 'pull_request'
+          ? `${GITHUB_WEB_ORIGIN}${githubPullPath(iss.repository, l.number)}`
+          : `${GITHUB_WEB_ORIGIN}${githubIssuePath(iss.repository, l.number)}`,
+      })),
+      // issue comments (kind:'issue' on the shared comment space) — the detail page renders
+      // these in its timeline; observed comments carry no body (labelled, never fabricated).
+      comments: foldedComments
+        .filter((c) => c.kind === 'issue' && c.repository === iss.repository && c.number === iss.number)
+        .map((c) => ({ id: c.id, author: c.body === undefined ? '(observed)' : 'simulator', body: c.body ?? `Comment observed — ${OBSERVED}.`, createdAt: c.created_at })),
+      // a derived timeline of state-change events (labeled/assigned/milestoned/locked/closed)
+      // mirroring the issue's current modeled state — the detail page renders it as a feed.
+      timeline: [
+        ...(iss.labels ?? []).map((name) => ({ event: 'labeled', detail: name })),
+        ...(iss.assignees ?? []).map((login) => ({ event: 'assigned', detail: `@${login}` })),
+        ...(iss.locked ? [{ event: 'locked', detail: iss.active_lock_reason ?? '' }] : []),
+        ...(iss.state === 'closed' ? [{ event: 'closed', detail: iss.state_reason ?? '' }] : []),
+      ],
+    };
+  });
+  // Reviews carry state/body for LOCAL writes; observed reviews carry neither, so we
+  // label them honestly as observed-only rather than fabricating review content.
+  const reviews = foldedReviews.map((r) => {
+    const observed = r.state === undefined && r.body === undefined;
+    return {
+      repo: r.repository,
+      number: r.number,
+      reviewer: observed ? '(observed)' : 'simulator',
+      state: r.state ?? 'reviewed',
+      body: r.body ?? (observed ? `Review observed — ${OBSERVED}.` : ''),
+      submittedAt: r.submitted_at,
+      observed,
+    };
+  });
+  // Issue comments and review (diff-thread) comments are split by kind so the client can
+  // render them in their right place. Observed comments carry no body — label them.
+  const toComment = (c: (typeof foldedComments)[number]) => {
+    const observed = c.body === undefined;
+    return {
+      repo: c.repository,
+      number: c.number,
+      author: observed ? '(observed)' : 'simulator',
+      body: c.body ?? (observed ? `Comment observed — ${OBSERVED}.` : ''),
+      createdAt: c.created_at,
+      observed,
+    };
+  };
+  const comments = foldedComments.filter((c) => c.kind === 'issue').map(toComment);
+  const reviewComments = foldedComments.filter((c) => c.kind === 'review').map(toComment);
+  // Actions (workflows + runs + jobs) — a LOCAL construct (running real CI is the only Actions
+  // non-goal; the run/job OBJECTS are modeled). Surfaced per-repo like PRs/issues. Runs carry
+  // status/conclusion the client renders as badges; jobs are scoped to a run by run_id.
+  const workflows = foldedWorkflows.map((w) => ({
+    repo: w.repository,
+    id: w.id,
+    name: w.name,
+    path: w.path,
+    state: w.state ?? 'active',
+  }));
+  const runs = workflowRuns.map((r) => {
+    const wf = foldedWorkflows.find((w) => w.repository === r.repository && w.id === r.workflow_id);
+    return {
+      repo: r.repository,
+      id: r.id,
+      workflowId: r.workflow_id,
+      workflowName: wf?.name ?? r.name,
+      name: r.name,
+      runNumber: r.run_number,
+      event: r.event,
+      status: r.status,
+      conclusion: r.conclusion,
+      headSha: r.head_sha,
+      headBranch: r.head_branch,
+      createdAt: r.created_at,
+      updatedAt: r.updated_at,
+      url: `${GITHUB_WEB_ORIGIN}/${r.repository}/actions/runs/${r.id}`,
+      jobCount: jobs.filter((j) => j.repository === r.repository && j.run_id === r.id).length,
+    };
+  });
+  const runJobs = jobs.map((j) => ({
+    repo: j.repository,
+    id: j.id,
+    runId: j.run_id,
+    name: j.name,
+    status: j.status,
+    conclusion: j.conclusion,
+    steps: j.steps.map((s) => ({ name: s.name, status: s.status, conclusion: s.conclusion, number: s.number })),
+  }));
+  // Releases (a LOCAL construct — there is no observed release evidence; release ASSETS are
+  // metadata only, the binary bytes are the declared Non-goal). Surfaced per-repo like PRs.
+  // Each release carries its tag/name/draft/prerelease flags + its asset catalog; tags are
+  // the published-release tag list (derived, no git blob bytes).
+  const releases = foldedReleases.map((r) => ({
+    repo: r.repository,
+    id: r.id,
+    tagName: r.tag_name,
+    name: r.name,
+    body: r.body,
+    draft: r.draft ?? false,
+    prerelease: r.prerelease ?? false,
+    createdAt: r.created_at,
+    publishedAt: r.published_at,
+    targetCommitish: r.target_commitish,
+    url: `${GITHUB_WEB_ORIGIN}/${r.repository}/releases/tag/${encodeURIComponent(r.tag_name)}`,
+    assets: releaseAssets
+      .filter((a) => a.repository === r.repository && a.release_id === r.id)
+      .map((a) => ({ id: a.id, name: a.name, label: a.label, contentType: a.content_type, size: a.size ?? 0, downloadCount: a.download_count ?? 0 })),
+  }));
+  const tagList = tags.map((t) => ({ repo: t.repository, name: t.name, commitSha: t.commit_sha }));
+  // Discussions (a LOCAL construct — no observed discussion evidence; modeled over REST,
+  // honestly noted as a deviation since real GitHub Discussions are GraphQL). Each discussion
+  // carries its category (resolved from the per-repo category list), state/lock, the chosen
+  // answer pointer, and its comments/replies (with the is_answer flag). Surfaced per-repo.
+  const discussionRepos = new Set(foldedDiscussions.map((d) => d.repository));
+  const categoryByRepoSlug = new Map<string, { name: string; emoji?: string; isAnswerable: boolean }>();
+  for (const r of discussionRepos) for (const c of discussionCategoriesFor(r, customCategories)) categoryByRepoSlug.set(`${r}#${c.slug}`, { name: c.name, emoji: c.emoji, isAnswerable: c.is_answerable ?? false });
+  const discussions = foldedDiscussions.map((d) => {
+    const cat = d.category_slug ? categoryByRepoSlug.get(`${d.repository}#${d.category_slug}`) : undefined;
+    const threadComments = foldedDiscussionComments.filter((c) => c.repository === d.repository && c.discussion_number === d.number);
+    return {
+      repo: d.repository,
+      number: d.number,
+      title: d.title,
+      body: d.body,
+      state: d.locked ? 'locked' : (d.state ?? 'open'),
+      locked: d.locked ?? false,
+      categorySlug: d.category_slug,
+      categoryName: cat?.name,
+      categoryEmoji: cat?.emoji,
+      isAnswerable: cat?.isAnswerable ?? false,
+      answerCommentId: d.answer_comment_id ?? null,
+      isAnswered: d.answer_comment_id != null,
+      commentsCount: threadComments.length,
+      createdAt: d.created_at,
+      updatedAt: d.updated_at,
+      url: `${GITHUB_WEB_ORIGIN}/${d.repository}/discussions/${d.number}`,
+      comments: threadComments.map((c) => ({
+        id: c.id,
+        parentId: c.parent_id ?? null,
+        body: c.body,
+        isAnswer: c.is_answer ?? false,
+        createdAt: c.created_at,
+      })),
+    };
+  });
+  // Repo contents (a LOCAL construct) — the Code/file browser tree. Each entry carries its
+  // path + size; the browser renders the directory tree per repo (no blob bytes rendered).
+  const contents = foldedContents.map((c) => ({ repo: c.repository, path: c.path, size: c.size, sha: c.sha, branch: c.branch ?? 'main' }));
+  // Notifications (a LOCAL construct) — the inbox screen. unread flag + reason + subject.
+  const notifications = foldedNotifications.map((n) => ({ id: n.id, repo: n.repository, title: n.subject_title, type: n.subject_type, reason: n.reason, unread: n.unread, updatedAt: n.updated_at }));
+  // Deployments (a LOCAL construct) — the repo's Deployments/Environments screen. Each
+  // deployment carries its environment + ref + the LATEST status (the deployment's state),
+  // mirroring GitHub's Environments view (most-recent deployment per environment, with state).
+  const deployments = foldedDeployments.map((d) => {
+    const statusesForDep = foldedDeploymentStatuses.filter((s) => s.deployment_id === d.id).sort((a, b) => b.id - a.id);
+    const latest = statusesForDep[0];
+    return {
+      repo: d.repository,
+      id: d.id,
+      ref: d.ref,
+      sha: d.sha,
+      environment: d.environment,
+      task: d.task,
+      description: d.description ?? undefined,
+      production: d.production_environment ?? false,
+      transient: d.transient_environment ?? false,
+      createdAt: d.created_at,
+      state: latest?.state ?? 'pending',
+      environmentUrl: latest?.environment_url,
+      url: `${GITHUB_WEB_ORIGIN}/${d.repository}/deployments`,
+      statuses: statusesForDep.map((s) => ({ id: s.id, state: s.state, description: s.description ?? undefined, createdAt: s.created_at })),
+    };
+  });
+  // Environments (a LOCAL construct) — protection-rule summaries per environment.
+  const environments = foldedEnvironments.map((e) => ({
+    repo: e.repository,
+    name: e.name,
+    waitTimer: e.wait_timer,
+    reviewers: e.reviewers ?? [],
+    protected: Boolean(e.wait_timer) || Boolean(e.reviewers?.length),
+  }));
+  // ── Projects v2 board (a LOCAL construct) — the Project board screen. Each project carries
+  //   its views (board/table) + its Status field's options as COLUMNS, and its items grouped
+  //   into those columns by their Status field value (the board's swim-lanes). Data-coupled:
+  //   seeding a project + a Status field + items moves the column counts the board renders.
+  const projectBoards = foldedProjects.map((p) => {
+    const fields = foldedProjectFields.filter((f) => f.project_id === p.id);
+    const statusField = fields.find((f) => f.data_type === 'single_select') ?? fields.find((f) => /status/i.test(f.name));
+    const columnNames = statusField?.options?.map((o) => o.name) ?? [];
+    const items = foldedProjectItems.filter((i) => i.project_id === p.id);
+    const columns = columnNames.map((name) => ({
+      name,
+      cards: items
+        .filter((i) => String((i.field_values as Record<string, unknown>)[statusField!.name] ?? '') === name)
+        .map((i) => ({ id: i.id, title: i.title ?? `#${i.content_id ?? i.id}`, contentType: i.content_type })),
+    }));
+    // items with no (or an unrecognized) status land in a "No Status" lane (GitHub behavior).
+    const noStatus = items.filter((i) => !columnNames.includes(String((i.field_values as Record<string, unknown>)[statusField?.name ?? ''] ?? '')));
+    return {
+      id: p.id, number: p.number, title: p.title, owner: p.owner, closed: p.closed ?? false,
+      views: foldedProjectViews.filter((v) => v.project_id === p.id).map((v) => ({ number: v.number, name: v.name, layout: v.layout })),
+      fields: fields.map((f) => ({ name: f.name, dataType: f.data_type })),
+      itemCount: items.length,
+      columns,
+      noStatus: { name: 'No Status', cards: noStatus.map((i) => ({ id: i.id, title: i.title ?? `#${i.content_id ?? i.id}`, contentType: i.content_type })) },
+      url: `${GITHUB_WEB_ORIGIN}/${p.owner_type === 'organization' ? 'orgs/' : 'users/'}${p.owner}/projects/${p.number}`,
+    };
+  });
+  // ── Insights / Pulse / Contributors (DERIVED per repo from the modeled PRs/issues/commits) —
+  //   the Pulse screen's counts (merged/opened PRs, opened/closed issues) + a contributors
+  //   leaderboard from the per-commit authors the twin tracks. Data-coupled: each new PR/issue
+  //   moves a Pulse count; each new commit author moves a contributor's commit total.
+  const repoNames = new Set<string>([...prs.map((p) => p.repository), ...issues.map((i) => i.repository), ...foldedRepos.map((r) => r.full_name)]);
+  const insights = [...repoNames].sort().map((repo) => {
+    const repoPrs = prs.filter((p) => p.repository === repo);
+    const repoIssues = issues.filter((i) => i.repository === repo);
+    const contribCounts = new Map<string, number>();
+    for (const pr of repoPrs) for (const c of pr.commits_list ?? []) { const a = c.author_name ?? '(unknown)'; contribCounts.set(a, (contribCounts.get(a) ?? 0) + 1); }
+    return {
+      repo,
+      pulse: {
+        mergedPrs: repoPrs.filter((p) => p.merged).length,
+        openPrs: repoPrs.filter((p) => !p.merged && (p.state ?? 'open') === 'open').length,
+        openedIssues: repoIssues.filter((i) => (i.state ?? 'open') === 'open').length,
+        closedIssues: repoIssues.filter((i) => i.state === 'closed').length,
+      },
+      contributors: [...contribCounts.entries()].map(([login, commits]) => ({ login, commits })).sort((a, b) => b.commits - a.commits),
+    };
+  });
+  // ── Settings (DERIVED per repo from the modeled repo config + collaborators/webhooks/branches)
+  //   the repo Settings screens (General / Collaborators / Webhooks / Branches). Data-coupled:
+  //   adding a collaborator or webhook moves the counts/rows the settings screen renders.
+  const settings = foldedRepos.map((r) => ({
+    repo: r.full_name,
+    general: { defaultBranch: r.default_branch, private: r.private ?? false, hasIssues: r.has_issues ?? true, hasProjects: r.has_projects ?? true, hasWiki: r.has_wiki ?? true, hasDiscussions: r.has_discussions ?? false, description: r.description ?? null },
+    collaborators: foldedCollaborators.filter((c) => c.repository === r.full_name).map((c) => ({ login: c.login, permission: c.permission })),
+    webhooks: foldedWebhooks.filter((h) => h.repository === r.full_name).map((h) => ({ id: h.id, url: h.url, active: h.active, events: h.events })),
+    branches: foldedBranches.filter((b) => b.repository === r.full_name).map((b) => ({ name: b.name, protected: b.protected ?? false })),
+  }));
+  return {
+    github: { pullRequests, issues: issuesOut, reviews, commits, comments, reviewComments, files, workflows, runs, jobs: runJobs, releases, tags: tagList, discussions, contents, notifications, deployments, environments, projectBoards, insights, settings },
+  };
+}