forge-workflow 0.0.10 → 0.1.0-beta.3

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/kernel/backing-issue.js

@@ -0,0 +1,311 @@
+'use strict';
+
+/**
+ * Auto Kernel Tracking — foundational primitive.
+ *
+ * `ensureBackingIssue()` guarantees that a unit of work (a branch/worktree) has a
+ * backing Kernel issue, WITHOUT anyone remembering to run `forge issue create`.
+ * It is the reusable core of the auto-tracking design
+ * (docs/work/2026-07-06-auto-kernel-tracking/design.md, kernel issue 67ab465b /
+ * PR1 131ab014); PR2/PR3 wire it into `forge worktree`, `forge push`, and the
+ * lefthook pre-push, but this module is deliberately side-effect-free beyond the
+ * injected kernel and never wires itself in.
+ *
+ * Contract (all guarantees are covered by test/kernel/backing-issue.test.js):
+ *   - Idempotent + deduped BY BRANCH: if the branch already resolves to an issue
+ *     (via the kernel_worktrees linkage row, or an issue id encoded in the branch
+ *     name), that issue is returned/linked — never a duplicate.
+ *   - Auto-creates a good-enough stub otherwise: title derived from the branch,
+ *     body noting it was auto-created, labelled `auto-stub`. Then links the branch.
+ *   - Skips work it should not track: main/master, detached HEAD (no branch), and
+ *     ignore-glob branches (tmp/spike/wip/throwaway). Returns null, creates nothing.
+ *   - Degrades gracefully: a missing/limited kernel, a non-kernel backend, or any
+ *     thrown error yields null (never throws) — so it is safe to call from a hook.
+ *   - Fully injectable: pass the kernel `driver` + `broker` (or a fake with the
+ *     same method surface), plus an optional clock (`now`) and id source
+ *     (`generateId`), so it is unit-testable without a real repo or sqlite DB.
+ *
+ * Storage choice: the branch->issue link lives in the `kernel_worktrees` row
+ * (`issue_id`, keyed by worktree `path`, with `branch` recorded) — the existing
+ * "the issue this branch serves" linkage cited by the design. No new table.
+ *
+ * @module kernel/backing-issue
+ */
+
+const { randomUUID } = require('node:crypto');
+
+const DEFAULT_PROTECTED_BRANCHES = Object.freeze(['main', 'master']);
+const DEFAULT_IGNORE_GLOBS = Object.freeze(['tmp/*', 'spike/*', 'wip/*', 'throwaway/*']);
+const AUTO_STUB_LABEL = 'auto-stub';
+// Branch prefixes stripped before deriving a title / probing for an encoded issue id.
+const BRANCH_PREFIX = /^(feat|feature|fix|bugfix|hotfix|chore|refactor|docs|test|spike|wip)\//i;
+// An issue key encoded in a branch slug, e.g. `feat/kap-7-foo` -> `kap-7`.
+const ENCODED_ISSUE_ID = /^([a-z][a-z0-9]*-\d+)\b/i;
+// Regex metacharacters escaped when compiling an ignore glob.
+const GLOB_METACHARS = '.+^${}()|[]\\';
+
+/**
+ * Resolve the injected kernel driver/broker from a variety of accepted shapes, so
+ * a caller can pass `{ driver, broker }`, the real `{ kernelDriver, kernelBroker }`
+ * from buildMigratedKernelIssueDeps(), or `{ kernel: <either> }`.
+ *
+ * @param {object} options
+ * @returns {{ driver: object|null, broker: object|null }}
+ */
+function resolveKernel(options) {
+  const kernel = options.kernel || {};
+  const driver = options.driver || options.kernelDriver || kernel.driver || kernel.kernelDriver || null;
+  const broker = options.broker || options.kernelBroker || kernel.broker || kernel.kernelBroker || null;
+  return { driver, broker };
+}
+
+/**
+ * @param {object} driver
+ * @returns {boolean} whether the driver exposes the worktree-linkage surface used here.
+ */
+function driverIsUsable(driver) {
+  return Boolean(
+    driver
+    && typeof driver.registerWorktree === 'function'
+    && (typeof driver.getWorktreeLinkage === 'function' || typeof driver.listWorktrees === 'function'),
+  );
+}
+
+/** @param {object} broker @returns {boolean} whether the broker can create issues. */
+function brokerIsUsable(broker) {
+  return Boolean(broker && typeof broker.runIssueOperation === 'function');
+}
+
+/** @param {string} glob @returns {RegExp} anchored regex; `*` = one segment, `**` = any. */
+function globToRegExp(glob) {
+  const source = String(glob);
+  let pattern = '';
+  for (let i = 0; i < source.length; i += 1) {
+    const char = source[i];
+    if (char === '*') {
+      if (source[i + 1] === '*') {
+        pattern += '.*';
+        i += 1;
+      } else {
+        pattern += '[^/]*';
+      }
+    } else if (GLOB_METACHARS.includes(char)) {
+      pattern += `\\${char}`;
+    } else {
+      pattern += char;
+    }
+  }
+  return new RegExp(`^${pattern}$`);
+}
+
+/**
+ * @param {string} branch
+ * @param {string[]} globs
+ * @returns {boolean} whether the branch matches any ignore glob.
+ */
+function matchesIgnoreGlob(branch, globs) {
+  return globs.some(glob => globToRegExp(glob).test(branch));
+}
+
+/**
+ * Decide whether the branch is a trackable unit of work.
+ *
+ * @param {string} branch
+ * @param {{ protectedBranches: string[], ignoreGlobs: string[] }} config
+ * @returns {{ skip: boolean, reason?: string }}
+ */
+function classifyBranch(branch, { protectedBranches, ignoreGlobs }) {
+  if (!branch || typeof branch !== 'string' || branch === 'HEAD') {
+    return { skip: true, reason: 'detached HEAD / no branch' };
+  }
+  if (protectedBranches.includes(branch)) {
+    return { skip: true, reason: `protected branch (${branch})` };
+  }
+  if (matchesIgnoreGlob(branch, ignoreGlobs)) {
+    return { skip: true, reason: `ignore-glob branch (${branch})` };
+  }
+  return { skip: false };
+}
+
+/** @param {string} branch @returns {string} branch slug with any known prefix removed. */
+function stripPrefix(branch) {
+  return branch.replace(BRANCH_PREFIX, '');
+}
+
+/**
+ * Derive a human-ish issue title from a branch name.
+ *
+ * @param {string} branch
+ * @returns {string}
+ */
+function deriveTitle(branch) {
+  const slug = stripPrefix(branch).replace(/[-_/]+/g, ' ').trim();
+  if (!slug) return branch;
+  return slug.charAt(0).toUpperCase() + slug.slice(1);
+}
+
+/**
+ * Extract an issue id encoded in the branch name (e.g. `feat/kap-7-foo` -> `kap-7`).
+ *
+ * @param {string} branch
+ * @returns {string|null}
+ */
+function extractEncodedIssueId(branch) {
+  const match = ENCODED_ISSUE_ID.exec(stripPrefix(branch));
+  return match ? match[1] : null;
+}
+
+/**
+ * Find an existing branch->issue linkage row (with a non-null issue_id). Prefers the
+ * path-keyed row; falls back to scanning by branch. Best-effort — returns null on any error.
+ *
+ * @param {object} driver
+ * @param {{ worktreePath?: string, branch: string }} query
+ * @returns {object|null} the linkage row, or null.
+ */
+function findExistingLink(driver, { worktreePath, branch }) {
+  try {
+    if (worktreePath && typeof driver.getWorktreeLinkage === 'function') {
+      const row = driver.getWorktreeLinkage({ path: worktreePath });
+      if (row && row.issue_id && row.branch === branch) return row;
+    }
+    if (typeof driver.listWorktrees === 'function') {
+      const rows = driver.listWorktrees() || [];
+      // Match ACTIVE (live) rows only: a superseded/stale registration for a
+      // reused branch name must not be treated as the existing link (be18881c —
+      // the third resolver, kept consistent with resolveActiveIssueId and
+      // currentBranchIssueFromDriver). Tolerate a null state for legacy rows.
+      const match = rows.find(row => row && row.branch === branch && row.issue_id
+        && (row.state === 'active' || row.state == null));
+      if (match) return match;
+    }
+  } catch {
+    return null;
+  }
+  return null;
+}
+
+/**
+ * Persist the branch->issue link into the kernel_worktrees registry.
+ *
+ * @param {object} driver
+ * @param {object} params
+ * @returns {object|null} the upserted row, or null on error.
+ */
+function linkBranchToIssue(driver, { projectRoot, worktreePath, gitCommonDir, branch, issueId, actor, now }) {
+  try {
+    return driver.registerWorktree({
+      git_common_dir: gitCommonDir || projectRoot || 'unknown',
+      path: worktreePath || projectRoot,
+      branch,
+      actor: actor || null,
+      issue_id: issueId,
+      work_folder: null,
+      registered_at: now().toISOString(),
+      state: 'active',
+    });
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Ensure the given branch has a backing Kernel issue. Idempotent, deduped by branch,
+ * best-effort (never throws). See the module doc for the full contract.
+ *
+ * @param {object} options
+ * @param {string} options.branch - Current branch (falsy or 'HEAD' => detached => skip).
+ * @param {string} [options.projectRoot] - Repo root; default worktree path / git-common-dir fallback.
+ * @param {string} [options.worktreePath] - Absolute worktree path (linkage row key). Defaults to projectRoot.
+ * @param {string} [options.gitCommonDir] - Git common dir for the linkage row.
+ * @param {object} [options.driver] - Kernel driver (real or fake). Also accepts kernelDriver / kernel.*.
+ * @param {object} [options.broker] - Kernel broker (real or fake). Also accepts kernelBroker / kernel.*.
+ * @param {string} [options.actor] - Actor recorded on the issue/linkage. Default FORGE_ACTOR or 'forge'.
+ * @param {string[]} [options.protectedBranches] - Never-track branches. Default ['main','master'].
+ * @param {string[]} [options.ignoreGlobs] - Never-track globs. Default tmp/spike/wip/throwaway.
+ * @param {() => Date} [options.now] - Clock injection. Default () => new Date().
+ * @param {() => string} [options.generateId] - Issue id source. Default randomUUID.
+ * @returns {Promise<{issueId: string, branch: string, created: boolean, existed: boolean, linked?: boolean, label?: string}|null>}
+ *   The backing issue descriptor, or null when the branch is skipped or the kernel is unavailable.
+ */
+async function ensureBackingIssue(options = {}) {
+  try {
+    const {
+      branch,
+      projectRoot,
+      worktreePath,
+      gitCommonDir,
+      actor = process.env.FORGE_ACTOR || 'forge',
+      protectedBranches = DEFAULT_PROTECTED_BRANCHES,
+      ignoreGlobs = DEFAULT_IGNORE_GLOBS,
+      now = () => new Date(),
+      generateId = randomUUID,
+    } = options;
+
+    // 1. Only track real units of work.
+    const classification = classifyBranch(branch, { protectedBranches, ignoreGlobs });
+    if (classification.skip) return null;
+
+    // 2. Kernel must be present + usable, else degrade (non-kernel backend / offline).
+    const { driver, broker } = resolveKernel(options);
+    if (!driverIsUsable(driver) || !brokerIsUsable(broker)) return null;
+
+    const linkParams = { projectRoot, worktreePath, gitCommonDir, branch, actor, now };
+
+    // 3. Idempotency: an existing branch->issue link wins (the common, cheap case).
+    const existing = findExistingLink(driver, { worktreePath, branch });
+    if (existing) {
+      return { issueId: existing.issue_id, branch, created: false, existed: true };
+    }
+
+    // 4. Dedupe: if the branch encodes an existing issue id, link that instead of
+    //    minting a stub.
+    const encodedId = extractEncodedIssueId(branch);
+    if (encodedId && typeof driver.loadKernelEntity === 'function') {
+      let entity = null;
+      try {
+        entity = await driver.loadKernelEntity('issue', encodedId);
+      } catch {
+        entity = null;
+      }
+      if (entity) {
+        // Report link persistence honestly: if registerWorktree failed (returns null),
+        // linked:false surfaces that the branch->issue link did NOT persist, so the
+        // idempotency guarantee is degraded (a later call may re-create) rather than
+        // silently claiming success. Callers/hooks can warn on linked:false.
+        const linked = linkBranchToIssue(driver, { ...linkParams, issueId: encodedId });
+        return { issueId: encodedId, branch, created: false, existed: true, linked: linked !== null };
+      }
+    }
+
+    // 5. Create a good-enough stub, then link the branch to it.
+    const issueId = generateId();
+    const title = deriveTitle(branch);
+    const body = `Auto-created stub for branch ${branch} — enrich with design/acceptance.`;
+    const createResult = await broker.runIssueOperation(
+      'create',
+      ['--id', issueId, '--title', title, '--body', body, '--label', AUTO_STUB_LABEL, '--type', 'task', '--status', 'open'],
+      { actor, origin: 'forge-autotrack', idempotencyKey: `issue.create:${issueId}` },
+    );
+    if (createResult && createResult.ok === false) return null;
+
+    const linked = linkBranchToIssue(driver, { ...linkParams, issueId });
+    return { issueId, branch, created: true, existed: false, linked: linked !== null, label: AUTO_STUB_LABEL };
+  } catch {
+    // Best-effort: a hook must never be broken by tracking. Degrade to null.
+    return null;
+  }
+}
+
+module.exports = {
+  ensureBackingIssue,
+  // Exported for focused unit tests / reuse by PR2-PR4 surfaces.
+  classifyBranch,
+  deriveTitle,
+  extractEncodedIssueId,
+  findExistingLink,
+  matchesIgnoreGlob,
+  DEFAULT_PROTECTED_BRANCHES,
+  DEFAULT_IGNORE_GLOBS,
+  AUTO_STUB_LABEL,
+};