Skip to content

Self-hosted, Self-Improving, Federated Everything App — dev management, agent orchestration, persistent mind, digital twin, second brain, and creative pipeline from a single dashboard over Tailscale to port the user into the OS

14.2 KB
Raw Blame
/**
 * Layered Intelligence — GitHub/GitLab forge filer (#2842 split of
 * layeredIntelligence.js). Lists/normalizes forge issues, resolves the
 * implementing PR + closing comment, and files/labels proposals through the
 * forge CLI (injectable `exec`).
 */

import { dispatchLabelSpec, forgeIssueLabels, isDispatchModel, isDispatchEffort } from '../../lib/dispatchLabels.js';
import { safeJSONParse } from '../../lib/fileUtils.js';
import { normalizeIssueState } from '../../lib/forgeIssueState.js';
import { LI_LABEL, LI_BLOCKING_LABEL, LI_LABEL_SPEC, LI_BLOCKING_LABEL_SPEC } from './constants.js';
import { slugMarker, extractSlugFromBody } from './dedup.js';
import { runCliBounded as runCli } from '../../lib/runCliBounded.js';
import { withGlabJson } from '../../lib/glabArgs.js';
import { fileForgeIssue, ensureForgeIssueLabels } from '../appIssues.js';

export { normalizeIssueState };

/**
 * Normalize a forge issue's labels to a plain `string[]`. gh reports objects
 * (`[{ name, color, … }]`); glab reports bare strings. Anything unrecognized
 * drops out rather than rendering `[object Object]` into the reasoner's prompt.
 */
export function normalizeIssueLabels(raw) {
  if (!Array.isArray(raw)) return [];
  return raw
    .map(l => (typeof l === 'string' ? l : l?.name))
    .filter(l => typeof l === 'string' && l.trim())
    .map(l => l.trim());
}

/**
 * Best-effort priority read from an issue's labels — there is no cross-forge
 * priority field, so the common label conventions are matched instead:
 * `priority: high` / `priority/high`, `P0`–`P4`, and a bare
 * `critical|urgent|high|medium|low` (optionally suffixed `-priority`).
 *
 * Returns null when no label looks like a priority. Null means "this issue
 * carries no priority label", NOT "priority zero" — the renderer omits the field
 * entirely rather than inventing a default the tracker never asserted.
 */
export function extractIssuePriority(labels = []) {
  const re = /^(?:priority[:/\s-]+(.+)|p([0-4])|(critical|urgent|high|medium|low)(?:[\s-]priority)?)$/i;
  for (const label of normalizeIssueLabels(labels)) {
    const m = label.match(re);
    if (!m) continue;
    const value = m[1] ?? (m[2] != null ? `p${m[2]}` : m[3]);
    if (typeof value === 'string' && value.trim()) return value.trim().toLowerCase();
  }
  return null;
}

/**
 * List issues on a forge. Defaults to the layered-intelligence set (open +
 * recently closed) for the reasoner + dedup guard; `label`/`state` are
 * parameterized so the plannedWork source (#2698) can reuse the exact same
 * parse/normalize path for the `plan`-labeled committed backlog.
 *
 * Returns `{ ok, issues }` — `ok:false` means the tracker read FAILED (CLI error
 * or unparseable output), which is NOT the same as "no existing issues" (`ok:true,
 * issues:[]`). The handler must NOT file when the read failed, or a transient
 * `gh` blip would defeat dedup and file a duplicate (AGENTS.md sentinel rule).
 */
export async function listForgeIssues({ cli, cwd, env, label = LI_LABEL, state = 'all', exec = runCli } = {}) {
  // glab lists open issues by default and needs `--all` to widen to every state;
  // gh takes the state explicitly.
  const args = cli === 'glab'
    ? withGlabJson(['issue', 'list', '--label', label, ...(state === 'all' ? ['--all'] : []), '-P', '100'])
    : ['issue', 'list', '--label', label, '--state', state, '--limit', '100', '--json', 'number,title,body,state,stateReason,closedAt,url,labels,comments,closedByPullRequestsReferences'];
  const { code, stdout } = await exec(cli, args, { cwd, env });
  if (code !== 0) return { ok: false, issues: [] };
  if (!stdout.trim()) return { ok: true, issues: [] };
  const parsed = safeJSONParse(stdout, null, { logError: false });
  if (!Array.isArray(parsed)) return { ok: false, issues: [] };
  return {
    ok: true,
    issues: parsed.map(i => ({
      number: i.number ?? i.iid ?? null,
      title: i.title || '',
      body: i.body || i.description || '',
      state: normalizeIssueState(i.state),
      // GitHub-only: 'completed' | 'not_planned' | 'reopened'. glab omits it, so
      // deriveOutcome falls back to treating any closed issue as merged.
      stateReason: i.stateReason || i.state_reason || null,
      closedAt: i.closedAt || i.closed_at || null,
      // gh reports `url`; glab reports `web_url`. Null when neither is present so
      // the overview's proposal links degrade to a plain count rather than a
      // dead href.
      url: i.url || i.web_url || null,
      labels: normalizeIssueLabels(i.labels),
      // The rejection classifier's last-resort signal (#2748): the prose a human
      // left when declining, for a close with no matching label/close-reason. gh
      // returns `comments` in the same batched list call (no extra fetch); glab's
      // JSON omits them, so its rows carry null and fall through to label/
      // stateReason only (tracked in the issue's Remaining).
      closingComment: extractClosingComment(i.comments),
      // The implementing-PR handle (#2748, deliverable 2): gh reports every PR that
      // closes/references this issue in `closedByPullRequestsReferences`. Additive
      // and null-defaulted — glab's JSON omits it, so its rows carry null and
      // fall through to the label/comment signals, and the reconciler only reads a
      // PR's state when it holds a number here. Scoped to the issue's own repo (parsed
      // from its url) so a cross-repo closing PR can't resolve to the wrong number.
      implementingPr: extractImplementingPr(i.closedByPullRequestsReferences, repoSlugFromUrl(i.url || i.web_url)),
      slug: extractSlugFromBody(i.body || i.description || '') || extractSlugFromBody(i.title || '')
    }))
  };
}

/**
 * Parse an `owner/repo` slug (lower-cased for case-insensitive compare) from a GitHub
 * issue/PR URL — `https://HOST/owner/repo/(issues|pull)/N` — host-agnostic so it works
 * on github.com and Enterprise. Returns null when the shape doesn't match.
 */
export function repoSlugFromUrl(url) {
  if (typeof url !== 'string') return null;
  const m = url.match(/^https?:\/\/[^/]+\/([^/]+)\/([^/]+)\/(?:issues|pull)\/\d+/);
  return m ? `${m[1]}/${m[2]}`.toLowerCase() : null;
}

/**
 * The `owner/repo` a `closedByPullRequestsReferences` entry belongs to — from its
 * structured `repository { owner { login }, name }`, falling back to parsing its `url`.
 * Null when neither is present. Lower-cased to match `repoSlugFromUrl`.
 */
function refRepoSlug(ref) {
  const owner = ref?.repository?.owner?.login;
  const name = ref?.repository?.name;
  if (typeof owner === 'string' && typeof name === 'string') return `${owner}/${name}`.toLowerCase();
  return repoSlugFromUrl(ref?.url);
}

/**
 * The number of the PR that implements a proposal, from gh's
 * `closedByPullRequestsReferences` (#2748, deliverable 2). Takes the LAST reference —
 * the most recent PR linked to the issue — and returns its number, or null when there
 * is none (glab, or an issue closed by hand). Pure.
 *
 * `selfRepo` (the issue's own `owner/repo`) scopes the match: the reconciler later runs
 * `gh pr view <number>` in the issue's checkout, so a reference from a DIFFERENT repo
 * (a cross-repo/fork PR that closed the issue) would resolve to the wrong PR number in
 * cwd's repo — or none — and mis-diagnose the rejection. So a ref whose repo is known
 * and differs from `selfRepo` is skipped. When `selfRepo` is unknown or a ref carries
 * no repo, it is accepted (same-repo is the overwhelmingly common case for an LI
 * proposal implemented in its own repo), preserving prior behavior.
 */
export function extractImplementingPr(refs, selfRepo = null) {
  if (!Array.isArray(refs)) return null;
  const self = typeof selfRepo === 'string' ? selfRepo.toLowerCase() : null;
  for (let i = refs.length - 1; i >= 0; i -= 1) {
    const n = refs[i]?.number;
    if (!Number.isInteger(n) || n <= 0) continue;
    const refRepo = refRepoSlug(refs[i]);
    if (self && refRepo && refRepo !== self) continue;
    return n;
  }
  return null;
}

/**
 * Read the merge state + check rollup of an implementing PR (#2748, deliverable 2),
 * so the rejection reconciler can classify `merge-conflict` / `validation-failed`.
 * gh-only (glab carries no PR handle) and bounded by the caller to the small set of
 * non-merged proposals that both hold a PR ref and were left undiagnosed by the free
 * signals — this is the ONE tracker fetch classification adds, and it never runs at
 * boot (only the scheduler-tick reconcile, gated behind `sources.outcomes`).
 * Returns `{ state, mergeStateStatus, statusCheckRollup }`, or null on any failure
 * (a null read simply leaves the proposal on its existing, honest fallback reason).
 */
export async function readImplementingPrState({ cli, cwd, env, number, exec = runCli } = {}) {
  if (cli !== 'gh' || !Number.isInteger(number)) return null;
  const { code, stdout } = await exec(cli, ['pr', 'view', String(number), '--json', 'state,mergeStateStatus,statusCheckRollup'], { cwd, env });
  if (code !== 0 || !stdout.trim()) return null;
  const parsed = safeJSONParse(stdout, null, { logError: false });
  if (!parsed || typeof parsed !== 'object') return null;
  return {
    state: parsed.state ?? null,
    mergeStateStatus: parsed.mergeStateStatus ?? null,
    statusCheckRollup: Array.isArray(parsed.statusCheckRollup) ? parsed.statusCheckRollup : []
  };
}

/**
 * The rationale a human left when closing a proposal, for the rejection classifier
 * (#2748). gh returns issue comments oldest-first; the LAST non-empty one sits
 * closest to the close, so it carries the decline reason in the common case.
 * Returns null for an issue closed with no comment — there is nothing to classify.
 */
export function extractClosingComment(comments) {
  if (!Array.isArray(comments)) return null;
  for (let i = comments.length - 1; i >= 0; i -= 1) {
    const body = comments[i]?.body;
    if (typeof body === 'string' && body.trim()) return body;
  }
  return null;
}

/**
 * List OPEN blocking-labeled issues for the app (park check). Returns
 * `{ ok, issues }` with the same failed-vs-empty distinction as listForgeIssues.
 */
export async function listBlockingIssues({ cli, cwd, env, exec = runCli } = {}) {
  const args = cli === 'glab'
    ? withGlabJson(['issue', 'list', '--label', LI_BLOCKING_LABEL, '-P', '100'])
    : ['issue', 'list', '--label', LI_BLOCKING_LABEL, '--state', 'open', '--limit', '100', '--json', 'number,title,state'];
  const { code, stdout } = await exec(cli, args, { cwd, env });
  if (code !== 0) return { ok: false, issues: [] };
  if (!stdout.trim()) return { ok: true, issues: [] };
  const parsed = safeJSONParse(stdout, null, { logError: false });
  if (!Array.isArray(parsed)) return { ok: false, issues: [] };
  return {
    ok: true,
    issues: parsed.map(i => ({
      number: i.number ?? i.iid ?? null,
      title: i.title || '',
      state: normalizeIssueState(i.state)
    }))
  };
}

/**
 * Ensure the layered-intelligence labels exist before the first `issue create`
 * (gh/glab both fail creating an issue with a non-existent label). Delegates
 * the actual create-and-tolerate-duplicates loop to `ensureForgeIssueLabels`
 * (#7687) — the same label-failure policy every forge filer now shares —
 * rather than re-running its own "already exists" check, and re-throws its
 * one hard-failure message so this function's own (pre-#7687) throwing
 * contract stays intact for `applyBlockingLabel` below.
 */
export async function ensureForgeLabels({ cli, cwd, env, extraLabels = [], exec = runCli } = {}) {
  const labels = [
    LI_LABEL_SPEC,
    LI_BLOCKING_LABEL_SPEC,
    ...extraLabels.map((name) => dispatchLabelSpec(name, { cli })).filter(Boolean),
  ];
  const error = await ensureForgeIssueLabels({ cli, exec, cwd, env, labels });
  if (error) throw new Error(error);
}

/**
 * File ONE proposal issue on a forge (gh/glab) — through the exec half every
 * forge filer shares (`fileForgeIssue`, #7687): create each label, embed the
 * slug marker in the body, create the issue, and parse `{ success, number,
 * url }` from the result. Required dispatch hints are validated before filing;
 * contributor labels remain optional — never derived from `complexity`.
 * `planner` is the identity of the model that REASONED this proposal (PortOS
 * knows it; the reasoner is never asked to name itself), applied as
 * `planner:<model>` (`planner::<model>` on GitLab).
 */
export async function fileProposalToForge({
  cli, cwd, env, hostname, title, body, slug, model, effort, goodFirstIssue, helpWanted, planner, exec = runCli
} = {}) {
  if (!isDispatchModel(model) || !isDispatchEffort(effort)) {
    return { success: false, error: 'Issue filing requires valid model and effort dispatch labels; investigate and supply both before retrying' };
  }
  const extras = forgeIssueLabels({ model, effort, goodFirstIssue, helpWanted, planner, cli })
    .map((name) => dispatchLabelSpec(name, { cli }));
  const labels = [LI_LABEL_SPEC, ...extras.filter(Boolean)];
  const result = await fileForgeIssue({ cli, cwd, env, hostname, title, body, trailer: `\n\n${slugMarker(slug)}`, labels, exec });
  return result.ok
    ? { success: true, number: result.number, url: result.url }
    : { success: false, error: result.error };
}

/**
 * Apply the blocking label to an existing issue (pause). Returns `{ success }`.
 *
 * The lazy `ensureForgeLabels` first is load-bearing, not defensive: both
 * `gh issue edit --add-label` and `glab issue update --label` fail the WHOLE
 * call with a 422 when the repo has never defined the named label, and this is
 * the only path that applies `LI_BLOCKING_LABEL` — so on any install where the
 * Layered Intelligence loop has not yet FILED an issue (`fileForgeIssue` covers
 * the issue-filing labels via the shared exec-half wrapper), the very first
 * pause would fail. Existing labels are accepted there, while other creation
 * failures are surfaced.
 */
export async function applyBlockingLabel({ cli, cwd, env, number, exec = runCli } = {}) {
  if (!Number.isInteger(number)) return { success: false, error: 'no issue number' };
  await ensureForgeLabels({ cli, cwd, env, exec });
  const args = cli === 'glab'
    ? ['issue', 'update', String(number), '--label', LI_BLOCKING_LABEL]
    : ['issue', 'edit', String(number), '--add-label', LI_BLOCKING_LABEL];
  const { code, stderr } = await exec(cli, args, { cwd, env });
  return code === 0 ? { success: true } : { success: false, error: stderr };
}