forge-workflow 0.0.9 → 0.1.0-beta.2

package/lib/issue-render.js

@@ -0,0 +1,220 @@
+'use strict';
+
+// Human-first rendering for the forge issue read surface (kernel issue a9bbd065,
+// 0.1.0 critical path). `forge ready`, `forge list`, and `forge show` default to
+// the compact text views below; the forge.issue.v1 JSON contract is unchanged and
+// stays available behind --json (or FORGE_JSON=1). Dependency-free by design: no
+// colors, no emoji, plain aligned text that survives any terminal or log file.
+
+const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+
+// Kernel UUIDs are unusable at a glance — display the 8-char prefix. Non-UUID ids
+// (legacy `forge-2agy.2` style) are already short and MUST stay full: they are the
+// only handle the CLI accepts. The full UUID remains accessible via `show` (which
+// prints it verbatim) and via --json everywhere.
+function shortId(id) {
+  if (typeof id !== 'string') return id == null ? '' : String(id);
+  return UUID_RE.test(id) ? id.slice(0, 8) : id;
+}
+
+// Human-readable display handle: `<title-slug>-<short-id>` (kernel 1db53c60), e.g.
+// "Add OAuth login" → "add-oauth-login-56a3a16d". The slug (first few title words) makes
+// a queue scannable at a glance; the short-id keeps it unique and resolvable — `forge show
+// <handle>` works because the resolver reads the trailing hex. The canonical id stays the
+// full UUID; the handle is display + lookup sugar, recomputed from the current title.
+function issueHandle(issue) {
+  const id = issue && issue.id != null ? String(issue.id) : '';
+  const short = shortId(id);
+  const title = issue && typeof issue.title === 'string' ? issue.title : '';
+  const slug = title
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-+|-+$/g, '')
+    .split('-')
+    .filter(Boolean)
+    .slice(0, 4)
+    .join('-');
+  return slug ? `${slug}-${short}` : short;
+}
+
+// gate.issue_verify (kernel 5f928cd0) attaches verified/mismatches to mutation
+// envelopes. Human mode must surface — never hide — a failed or unconfirmed
+// read-back, mirroring the JSON envelope's verified/mismatches keys.
+function verificationLines(envelope) {
+  if (!envelope || envelope.verified === undefined || envelope.verified === true) {
+    return [];
+  }
+  if (envelope.verified === false) {
+    const lines = ['WARNING: read-back verification failed (gate.issue_verify):'];
+    for (const mismatch of Array.isArray(envelope.mismatches) ? envelope.mismatches : []) {
+      lines.push(`  - ${mismatch}`);
+    }
+    return lines;
+  }
+  // verified === null — the verification read itself failed.
+  return ['WARNING: read-back verification could not confirm the result (gate.issue_verify).'];
+}
+
+// Render rows as space-aligned columns. Every column except the last is padded to
+// its widest cell; the last (title) runs free so long titles never distort the grid.
+function renderTable(headers, rows) {
+  const all = [headers, ...rows];
+  const widths = headers.map((_, column) => (
+    column === headers.length - 1
+      ? 0
+      : Math.max(...all.map(row => String(row[column] ?? '').length))
+  ));
+  return all.map(row => row
+    .map((cell, column) => {
+      const text = String(cell ?? '');
+      return column === row.length - 1 ? text : text.padEnd(widths[column]);
+    })
+    .join('  ')
+    .replace(/\s+$/, ''));
+}
+
+// forge ready / forge list: one aligned row per issue. Columns mirror the triage
+// decision: which issue (short id), what it is (type), where it stands (status),
+// how urgent (priority), and what it says (title).
+function renderIssueList(envelope, { emptyMessage = 'No issues found.' } = {}) {
+  const data = envelope && envelope.data && typeof envelope.data === 'object' ? envelope.data : {};
+  const issues = Array.isArray(data.issues) ? data.issues : [];
+  const lines = [];
+
+  if (issues.length === 0) {
+    lines.push(emptyMessage);
+  } else {
+    lines.push(...renderTable(
+      ['ID', 'TYPE', 'STATUS', 'PRIORITY', 'TITLE'],
+      issues.map(issue => [
+        issueHandle(issue),
+        issue.type ?? '-',
+        issue.status ?? '-',
+        issue.priority ?? '-',
+        issue.title ?? '',
+      ]),
+    ));
+    lines.push('');
+    lines.push(`${issues.length} issue${issues.length === 1 ? '' : 's'}`);
+  }
+
+  lines.push(...verificationLines(envelope));
+  return lines.join('\n');
+}
+
+function pushField(lines, label, value) {
+  if (value === null || value === undefined || value === '' || (Array.isArray(value) && value.length === 0)) {
+    return;
+  }
+  lines.push(`${label}: ${Array.isArray(value) ? value.join(', ') : value}`);
+}
+
+function pushSection(lines, label, text) {
+  if (typeof text !== 'string' || text.trim() === '') return;
+  lines.push('', `${label}:`, text);
+}
+
+// forge show: the full detail view. This is the surface that prints the FULL id
+// (list/ready show only the 8-char prefix), so every field a script or human
+// needs to act on the issue is reachable without --json.
+function renderIssueShow(envelope) {
+  const issue = envelope && envelope.data && typeof envelope.data === 'object' ? envelope.data : {};
+  const lines = [];
+
+  lines.push(issue.title ?? '(untitled)');
+  lines.push(String(issue.id ?? ''));
+  lines.push('');
+
+  const status = issue.blocked === true ? `${issue.status ?? '-'} (blocked)` : (issue.status ?? '-');
+  const core = [`Type: ${issue.type ?? '-'}`, `Status: ${status}`, `Priority: ${issue.priority ?? '-'}`];
+  if (issue.rank !== null && issue.rank !== undefined) core.push(`Rank: ${issue.rank}`);
+  lines.push(core.join('  '));
+
+  pushField(lines, 'Labels', issue.labels);
+  pushField(lines, 'Assignee', issue.assignee);
+  pushField(lines, 'Claimed by', issue.claimed_by);
+  pushField(lines, 'Parent', shortId(issue.parent_id ?? null) || null);
+  pushField(lines, 'Blocked by', Array.isArray(issue.blocked_by) ? issue.blocked_by.map(shortId) : null);
+  pushField(lines, 'Dependencies', Array.isArray(issue.dependencies) ? issue.dependencies.map(shortId) : null);
+  pushField(lines, 'Dependents', Array.isArray(issue.dependents) ? issue.dependents.map(shortId) : null);
+  pushField(lines, 'Created', issue.created_at);
+  pushField(lines, 'Updated', issue.updated_at);
+  if (issue.closed_at) {
+    pushField(lines, 'Closed', issue.close_reason ? `${issue.closed_at} (${issue.close_reason})` : issue.closed_at);
+  }
+
+  if (typeof issue.body === 'string' && issue.body.trim() !== '') {
+    lines.push('', issue.body);
+  }
+  pushSection(lines, 'Acceptance criteria', issue.acceptance_criteria);
+  pushSection(lines, 'Design', issue.design);
+  pushSection(lines, 'Notes', issue.notes);
+
+  const comments = Array.isArray(issue.comments) ? issue.comments : [];
+  if (comments.length > 0) {
+    lines.push('', `Comments (${comments.length}):`);
+    for (const comment of comments) {
+      const meta = [comment.created_at, comment.actor].filter(Boolean).join(' ');
+      lines.push(`  [${meta}] ${comment.body ?? ''}`);
+    }
+  }
+
+  const verification = verificationLines(envelope);
+  if (verification.length > 0) {
+    lines.push('', ...verification);
+  }
+  return lines.join('\n');
+}
+
+// Write subcommands → the past-tense verb used in their confirmation line.
+const MUTATION_VERBS = {
+  create: 'Created',
+  update: 'Updated',
+  claim: 'Claimed',
+  release: 'Released',
+  comment: 'Commented on',
+  close: 'Closed',
+};
+
+// Concise, human-first confirmation for a write, used only at an interactive terminal
+// (piped/non-interactive callers keep the machine-parseable JSON envelope — see the
+// TTY gate in lib/commands/_issue.js).
+function renderIssueMutation(subcommand, envelope) {
+  const issue = envelope && envelope.data && typeof envelope.data === 'object' ? envelope.data : {};
+  const verb = MUTATION_VERBS[subcommand] || 'Updated';
+  // Use the readable handle (slug-shortid) so a stream of confirmations stays scannable,
+  // consistent with `forge list`/`ready` (kernel 1db53c60).
+  const handle = issueHandle(issue) || '(issue)';
+  let headline = `✓ ${verb} ${handle}`;
+  if (issue.status) {
+    headline += `  [${issue.status}]`;
+  }
+  const lines = [headline];
+  const verification = verificationLines(envelope);
+  if (verification.length > 0) {
+    lines.push(...verification);
+  }
+  return lines.join('\n');
+}
+
+// Dispatch a human rendering for one subcommand's success envelope.
+function renderIssueEnvelope(subcommand, envelope) {
+  if (MUTATION_VERBS[subcommand]) {
+    return renderIssueMutation(subcommand, envelope);
+  }
+  if (subcommand === 'show') {
+    return renderIssueShow(envelope);
+  }
+  return renderIssueList(envelope, {
+    emptyMessage: subcommand === 'ready' ? 'No ready issues.' : 'No issues found.',
+  });
+}
+
+module.exports = {
+  shortId,
+  issueHandle,
+  renderIssueList,
+  renderIssueShow,
+  renderIssueMutation,
+  renderIssueEnvelope,
+};

package/lib/issue-sync/authority.js

@@ -0,0 +1,100 @@
+const GITHUB_OWNED_FIELDS = new Set([
+  'github.number',
+  'github.nodeId',
+  'github.url',
+  'shared.title',
+  'shared.body',
+  'shared.state',
+  'shared.assignees',
+  'shared.labels',
+  'shared.milestone',
+  'sync.remoteUpdatedAt',
+]);
+
+const FORGE_OWNED_FIELDS = new Set([
+  'forge.issueId',
+  'forge.dependencies',
+  'forge.parentId',
+  'forge.childIds',
+  'forge.workflowStage',
+  'forge.acceptanceCriteria',
+  'forge.progressNotes',
+  'forge.stageTransitions',
+  'forge.decisions',
+  'forge.memory',
+  'sync.lastPulledAt',
+  'sync.lastPushedAt',
+  'sync.pendingOutbound',
+  'sync.drift',
+]);
+
+const CACHE_FIELDS = new Set([
+  'cache.githubSnapshot',
+  'cache.materializedIssue',
+  'cache.legacyLinkHints.mapping',
+  'cache.legacyLinkHints.githubIssue',
+  'cache.legacyLinkHints.syncComments',
+  'cache.legacyLinkHints.externalRef',
+  'cache.legacyLinkHints.descriptionUrl',
+]);
+
+function matchesFieldPath(fieldPath, knownFieldPath) {
+  return fieldPath === knownFieldPath || fieldPath.startsWith(`${knownFieldPath}.`);
+}
+
+function hasFieldPath(fieldPath, fieldSet) {
+  if (typeof fieldPath !== 'string' || fieldPath.length === 0) {
+    return false;
+  }
+
+  for (const knownFieldPath of fieldSet) {
+    if (matchesFieldPath(fieldPath, knownFieldPath)) {
+      return true;
+    }
+  }
+
+  return false;
+}
+
+function getFieldAuthority(fieldPath) {
+  if (hasFieldPath(fieldPath, GITHUB_OWNED_FIELDS)) {
+    return 'github';
+  }
+
+  if (hasFieldPath(fieldPath, FORGE_OWNED_FIELDS)) {
+    return 'forge';
+  }
+
+  if (hasFieldPath(fieldPath, CACHE_FIELDS)) {
+    return 'cache';
+  }
+
+  return null;
+}
+
+function isGitHubOwnedField(fieldPath) {
+  return getFieldAuthority(fieldPath) === 'github';
+}
+
+function isForgeOwnedField(fieldPath) {
+  return getFieldAuthority(fieldPath) === 'forge';
+}
+
+function isCacheField(fieldPath) {
+  return getFieldAuthority(fieldPath) === 'cache';
+}
+
+function isSharedField(fieldPath) {
+  return typeof fieldPath === 'string' && fieldPath.startsWith('shared.') && isGitHubOwnedField(fieldPath);
+}
+
+module.exports = {
+  CACHE_FIELDS,
+  FORGE_OWNED_FIELDS,
+  GITHUB_OWNED_FIELDS,
+  getFieldAuthority,
+  isCacheField,
+  isForgeOwnedField,
+  isGitHubOwnedField,
+  isSharedField,
+};

package/lib/issue-sync/github-pull.js

@@ -0,0 +1,184 @@
+'use strict';
+
+const { normalizeGitHubNumber } = require('./link-store.js');
+
+const GITHUB_OWNED_FIELD_PATHS = [
+  'github.number',
+  'github.nodeId',
+  'github.url',
+  'shared.title',
+  'shared.body',
+  'shared.state',
+  'shared.assignees',
+  'shared.labels',
+  'shared.milestone',
+  'sync.remoteUpdatedAt',
+];
+
+function cloneValue(value) {
+  if (Array.isArray(value)) {
+    return value.map(cloneValue);
+  }
+
+  if (value && typeof value === 'object') {
+    const copy = {};
+
+    for (const [key, nestedValue] of Object.entries(value)) {
+      copy[key] = cloneValue(nestedValue);
+    }
+
+    return copy;
+  }
+
+  return value;
+}
+
+function normalizeText(value, fallback = '') {
+  return typeof value === 'string' ? value : fallback;
+}
+
+function normalizeState(value) {
+  if (typeof value === 'string' && value.length > 0) {
+    return value;
+  }
+
+  return 'open';
+}
+
+function normalizeCollectionEntries(values) {
+  if (Array.isArray(values)) {
+    return values;
+  }
+
+  if (!values) {
+    return [];
+  }
+
+  if (typeof values === 'object') {
+    if (Array.isArray(values.nodes)) {
+      return values.nodes;
+    }
+
+    if (Array.isArray(values.edges)) {
+      return values.edges
+        .map((edge) => edge?.node ?? edge)
+        .filter((entry) => entry != null);
+    }
+  }
+
+  return [values];
+}
+
+function normalizeNameList(values) {
+  const source = normalizeCollectionEntries(values);
+  const normalized = [];
+  const seen = new Set();
+
+  for (const entry of source) {
+    const name = typeof entry === 'string'
+      ? entry
+      : entry?.login ?? entry?.name ?? entry?.title ?? null;
+
+    if (typeof name !== 'string' || name.length === 0 || seen.has(name)) {
+      continue;
+    }
+
+    seen.add(name);
+    normalized.push(name);
+  }
+
+  return normalized;
+}
+
+function normalizeMilestone(milestone) {
+  if (!milestone) {
+    return null;
+  }
+
+  if (typeof milestone === 'string') {
+    return milestone;
+  }
+
+  return milestone.title ?? milestone.name ?? null;
+}
+
+function normalizeNodeId(issue = {}) {
+  if (typeof issue.node_id === 'string' && issue.node_id.length > 0) {
+    return issue.node_id;
+  }
+
+  if (typeof issue.nodeId === 'string' && issue.nodeId.length > 0) {
+    return issue.nodeId;
+  }
+
+  if (typeof issue.id === 'string' && issue.id.length > 0) {
+    return issue.id;
+  }
+
+  return null;
+}
+
+function normalizeIssueUrl(issue = {}) {
+  const candidates = [issue.html_url, issue.htmlUrl, issue.url];
+
+  for (const candidate of candidates) {
+    if (typeof candidate !== 'string' || candidate.length === 0) {
+      continue;
+    }
+
+    if (/^https:\/\/api\.github\.com\//iu.test(candidate)) {
+      continue;
+    }
+
+    return candidate;
+  }
+
+  return null;
+}
+
+function normalizeAssignees(issue = {}) {
+  const assignees = normalizeNameList(issue.assignees);
+
+  if (assignees.length > 0) {
+    return assignees;
+  }
+
+  return normalizeNameList(issue.assignee);
+}
+
+function normalizeRemoteIssue(issue = {}) {
+  return {
+    github: {
+      number: normalizeGitHubNumber(issue.number ?? issue.issue_number ?? issue.issueNumber),
+      nodeId: normalizeNodeId(issue),
+      url: normalizeIssueUrl(issue),
+    },
+    shared: {
+      title: normalizeText(issue.title),
+      body: normalizeText(issue.body),
+      state: normalizeState(issue.state),
+      assignees: normalizeAssignees(issue),
+      labels: normalizeNameList(issue.labels),
+      milestone: normalizeMilestone(issue.milestone),
+    },
+    sync: {
+      remoteUpdatedAt: issue.updated_at ?? issue.updatedAt ?? null,
+    },
+  };
+}
+
+const normalizeGitHubIssuePayload = normalizeRemoteIssue;
+
+module.exports = {
+  GITHUB_OWNED_FIELD_PATHS,
+  cloneValue,
+  normalizeGitHubIssuePayload,
+  normalizeAssignees,
+  normalizeCollectionEntries,
+  normalizeIssueUrl,
+  normalizeMilestone,
+  normalizeNameList,
+  normalizeNodeId,
+  normalizeRemoteIssue,
+  normalizeState,
+};

package/lib/issue-sync/import-primitives.js

@@ -0,0 +1,98 @@
+'use strict';
+
+const { cloneValue, normalizeRemoteIssue: normalizeSharedRemoteIssue } = require('./github-pull.js');
+const { reconcileSharedIssueRecord } = require('./reconcile.js');
+const { resolveCanonicalLink } = require('./link-store.js');
+
+function toIssueArray(page = {}) {
+  if (Array.isArray(page)) {
+    return page;
+  }
+
+  if (!page || typeof page !== 'object') {
+    return [];
+  }
+
+  if (Array.isArray(page.nodes)) {
+    return page.nodes;
+  }
+
+  if (Array.isArray(page.items)) {
+    return page.items;
+  }
+
+  if (Array.isArray(page.issues)) {
+    return page.issues;
+  }
+
+  if (Array.isArray(page.edges)) {
+    return page.edges.map((edge) => edge?.node).filter(Boolean);
+  }
+
+  const nestedNodes = page.data?.repository?.issues?.nodes;
+  if (Array.isArray(nestedNodes)) {
+    return nestedNodes;
+  }
+
+  const nestedEdges = page.data?.repository?.issues?.edges;
+  if (Array.isArray(nestedEdges)) {
+    return nestedEdges.map((edge) => edge?.node).filter(Boolean);
+  }
+
+  return [];
+}
+
+function listRemoteIssues(page = {}) {
+  return toIssueArray(page).map(cloneValue);
+}
+
+function normalizeRemoteIssue(issue = {}) {
+  return normalizeSharedRemoteIssue(issue);
+}
+
+function resolveSharedLink(linkStore, remoteIssue = {}) {
+  if (!linkStore) {
+    return null;
+  }
+
+  const lookup = {
+    githubNodeId: remoteIssue.github?.nodeId ?? remoteIssue.node_id ?? remoteIssue.nodeId ?? null,
+    githubNumber: remoteIssue.github?.number ?? remoteIssue.number ?? remoteIssue.issue_number ?? remoteIssue.issueNumber ?? null,
+  };
+
+  if (typeof linkStore.resolveCanonicalLink === 'function') {
+    return linkStore.resolveCanonicalLink(lookup);
+  }
+
+  if (typeof linkStore === 'object' && typeof linkStore.byGitHubNumber?.get === 'function') {
+    return resolveCanonicalLink(linkStore, lookup);
+  }
+
+  return null;
+}
+
+function materializeLocalIssue(localRecord = {}, remoteIssue = {}, linkStore, options = {}) {
+  const normalizedRemoteIssue = remoteIssue?.github && remoteIssue?.shared && remoteIssue?.sync
+    ? cloneValue(remoteIssue)
+    : normalizeRemoteIssue(remoteIssue);
+
+  const link = resolveSharedLink(linkStore, normalizedRemoteIssue);
+  const { record, diagnostics } = reconcileSharedIssueRecord(
+    localRecord,
+    normalizedRemoteIssue,
+    options.reconcileOptions ?? {},
+  );
+
+  return {
+    link,
+    diagnostics,
+    record,
+  };
+}
+
+module.exports = {
+  listRemoteIssues,
+  materializeLocalIssue,
+  normalizeRemoteIssue,
+  resolveSharedLink,
+};