@nforma.ai/nforma 0.2.1 → 0.28.0

package/bin/observe-handler-upstream.cjs

@@ -0,0 +1,251 @@
+/**
+ * Upstream tracking handler for /nf:observe
+ * Fetches releases (and notable PRs for loose coupling) from upstream repos via gh CLI
+ *
+ * Coupling modes:
+ *   tight  — All releases since last check (evaluate for cherry-pick — our code may already be better)
+ *   loose  — Releases + notable merged PRs (inspirational — patterns, features, hardening)
+ *
+ * State persisted in .planning/upstream-state.json to track last-checked date per upstream
+ */
+
+const { execFileSync } = require('node:child_process');
+const fs = require('node:fs');
+const path = require('node:path');
+const { parseDuration, formatAge } = require('./observe-utils.cjs');
+
+const STATE_FILE = '.planning/upstream-state.json';
+
+// Keywords that signal an inspirational change worth surfacing (loose coupling)
+const INSPIRATION_KEYWORDS = [
+  'feat', 'feature', 'pattern', 'harden', 'security', 'perf', 'refactor',
+  'breaking', 'architecture', 'plugin', 'hook', 'workflow', 'agent'
+];
+
+/**
+ * Load upstream state (last-checked timestamps per repo)
+ * @param {string} [basePath]
+ * @returns {object} { [repo]: { last_checked: ISO8601, last_release_tag: string } }
+ */
+function loadUpstreamState(basePath) {
+  const stateFile = path.resolve(basePath || process.cwd(), STATE_FILE);
+  try {
+    return JSON.parse(fs.readFileSync(stateFile, 'utf8'));
+  } catch {
+    return {};
+  }
+}
+
+/**
+ * Save upstream state
+ * @param {object} state
+ * @param {string} [basePath]
+ */
+function saveUpstreamState(state, basePath) {
+  const stateFile = path.resolve(basePath || process.cwd(), STATE_FILE);
+  const dir = path.dirname(stateFile);
+  if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true });
+  fs.writeFileSync(stateFile, JSON.stringify(state, null, 2) + '\n');
+}
+
+/**
+ * Fetch releases from upstream repo since a cutoff date
+ * @param {string} repo - owner/repo
+ * @param {string} since - ISO8601 cutoff
+ * @param {number} limit
+ * @param {Function} execFn
+ * @returns {Array} releases
+ */
+function fetchReleases(repo, since, limit, execFn) {
+  const execFile = execFn || execFileSync;
+  try {
+    const output = execFile('gh', [
+      'release', 'list', '--repo', repo,
+      '--limit', String(limit),
+      '--json', 'tagName,name,publishedAt,isPrerelease,url'
+    ], { encoding: 'utf8' });
+    let releases = JSON.parse(output);
+    if (since) {
+      const cutoff = new Date(since).getTime();
+      releases = releases.filter(r => new Date(r.publishedAt).getTime() > cutoff);
+    }
+    return releases;
+  } catch {
+    return [];
+  }
+}
+
+/**
+ * Fetch notable merged PRs from upstream repo (for loose/inspirational coupling)
+ * Filters by keyword matches in title or size threshold
+ * @param {string} repo
+ * @param {string} since - ISO8601 cutoff
+ * @param {number} limit
+ * @param {Function} execFn
+ * @returns {Array} PRs
+ */
+function fetchNotablePRs(repo, since, limit, execFn) {
+  const execFile = execFn || execFileSync;
+  try {
+    const output = execFile('gh', [
+      'pr', 'list', '--repo', repo,
+      '--state', 'merged',
+      '--limit', String(limit * 3), // fetch more, filter down
+      '--json', 'number,title,url,mergedAt,changedFiles,additions,deletions,labels'
+    ], { encoding: 'utf8' });
+    let prs = JSON.parse(output);
+
+    // Filter by date
+    if (since) {
+      const cutoff = new Date(since).getTime();
+      prs = prs.filter(pr => pr.mergedAt && new Date(pr.mergedAt).getTime() > cutoff);
+    }
+
+    // Filter for "notable" PRs — keyword match OR substantial size
+    prs = prs.filter(pr => {
+      const title = (pr.title || '').toLowerCase();
+      const hasKeyword = INSPIRATION_KEYWORDS.some(kw => title.includes(kw));
+      const isSubstantial = (pr.changedFiles || 0) >= 5 || (pr.additions || 0) >= 100;
+      return hasKeyword || isSubstantial;
+    });
+
+    return prs.slice(0, limit);
+  } catch {
+    return [];
+  }
+}
+
+/**
+ * Classify severity/interest level from release or PR
+ * @param {object} item - release or PR object
+ * @param {string} itemType - 'release' or 'pr'
+ * @returns {string} severity string
+ */
+function classifyUpstreamSeverity(item, itemType) {
+  if (itemType === 'release') {
+    const name = ((item.name || '') + ' ' + (item.tagName || '')).toLowerCase();
+    if (name.includes('breaking') || /\d+\.0\.0/.test(item.tagName || '')) return 'warning';
+    if (item.isPrerelease) return 'info';
+    return 'info';
+  }
+  // PR
+  const title = (item.title || '').toLowerCase();
+  if (title.includes('breaking') || title.includes('security') || title.includes('harden')) return 'warning';
+  if (title.includes('feat') || title.includes('pattern') || title.includes('refactor')) return 'info';
+  return 'info';
+}
+
+/**
+ * Upstream source handler
+ * @param {object} sourceConfig - { type, label, repo, coupling, branch?, filter?: { since } }
+ * @param {object} options - { sinceOverride?, limitOverride?, execFn?, basePath? }
+ * @returns {object} Standard observe schema result
+ */
+function handleUpstream(sourceConfig, options) {
+  const label = sourceConfig.label || 'Upstream';
+  const execFile = options.execFn || execFileSync;
+  const basePath = options.basePath || process.cwd();
+  const coupling = sourceConfig.coupling || 'loose';
+  const repo = sourceConfig.repo;
+
+  if (!repo) {
+    return {
+      source_label: label,
+      source_type: 'upstream',
+      status: 'error',
+      error: 'No repo configured for upstream source',
+      issues: []
+    };
+  }
+
+  try {
+    // Determine cutoff date
+    const state = loadUpstreamState(basePath);
+    const repoState = state[repo] || {};
+    const filter = sourceConfig.filter || {};
+    const sinceOverride = options.sinceOverride || filter.since;
+
+    let since;
+    if (repoState.last_checked) {
+      since = repoState.last_checked;
+    } else if (sinceOverride) {
+      const ms = parseDuration(sinceOverride);
+      since = ms > 0 ? new Date(Date.now() - ms).toISOString() : null;
+    } else {
+      // Default: 14 days for first run
+      since = new Date(Date.now() - 14 * 86400000).toISOString();
+    }
+
+    const limit = options.limitOverride || filter.limit || 10;
+    const issues = [];
+
+    // Both tight and loose get releases
+    const releases = fetchReleases(repo, since, limit, execFile);
+    for (const rel of releases) {
+      issues.push({
+        id: `upstream-rel-${repo}-${rel.tagName}`,
+        title: `[${coupling === 'tight' ? 'Evaluate' : 'Inspiration'}] ${rel.name || rel.tagName}`,
+        severity: classifyUpstreamSeverity(rel, 'release'),
+        url: rel.url || `https://github.com/${repo}/releases/tag/${rel.tagName}`,
+        age: formatAge(rel.publishedAt),
+        created_at: rel.publishedAt || new Date().toISOString(),
+        meta: `${repo} ${rel.tagName}${rel.isPrerelease ? ' (pre-release)' : ''}`,
+        source_type: 'upstream',
+        issue_type: 'upstream',
+        _upstream: { coupling, repo, tag: rel.tagName }
+      });
+    }
+
+    // Loose coupling: also fetch notable merged PRs
+    if (coupling === 'loose') {
+      const prs = fetchNotablePRs(repo, since, limit, execFile);
+      for (const pr of prs) {
+        issues.push({
+          id: `upstream-pr-${repo}-${pr.number}`,
+          title: `[Inspiration] ${pr.title}`,
+          severity: classifyUpstreamSeverity(pr, 'pr'),
+          url: pr.url || `https://github.com/${repo}/pull/${pr.number}`,
+          age: formatAge(pr.mergedAt),
+          created_at: pr.mergedAt || new Date().toISOString(),
+          meta: `${repo} #${pr.number} (+${pr.additions || 0}/-${pr.deletions || 0}, ${pr.changedFiles || 0} files)`,
+          source_type: 'upstream',
+          issue_type: 'upstream',
+          _upstream: { coupling, repo, pr: pr.number }
+        });
+      }
+    }
+
+    // Update state
+    state[repo] = {
+      last_checked: new Date().toISOString(),
+      last_release_tag: releases.length > 0 ? releases[0].tagName : (repoState.last_release_tag || null),
+      coupling
+    };
+    saveUpstreamState(state, basePath);
+
+    return {
+      source_label: label,
+      source_type: 'upstream',
+      status: 'ok',
+      issues
+    };
+  } catch (err) {
+    return {
+      source_label: label,
+      source_type: 'upstream',
+      status: 'error',
+      error: `Upstream fetch failed: ${err.message}`,
+      issues: []
+    };
+  }
+}
+
+module.exports = {
+  handleUpstream,
+  loadUpstreamState,
+  saveUpstreamState,
+  fetchReleases,
+  fetchNotablePRs,
+  classifyUpstreamSeverity,
+  INSPIRATION_KEYWORDS
+};

package/bin/observe-handlers.cjs

@@ -1,5 +1,5 @@
 /**
- * Source handler implementations for /qgsd:observe
+ * Source handler implementations for /nf:observe
  * GitHub, Sentry, sentry-feedback, and bash handlers
  *
  * ALL handlers return the SAME schema:
@@ -10,42 +10,11 @@
  */
 
 const { execFileSync } = require('node:child_process');
+const { parseDuration, formatAge } = require('./observe-utils.cjs');
 
 // Severity labels recognized from GitHub labels (ordered by priority)
 const SEVERITY_LABELS = ['critical', 'error', 'bug', 'warning', 'enhancement', 'info'];
 
-/**
- * Parse a duration string like "7d", "24h", "30m" into milliseconds
- * @param {string} duration - Duration string
- * @returns {number} Milliseconds
- */
-function parseDuration(duration) {
-  if (!duration) return 0;
-  const match = String(duration).match(/^(\d+)([dhms])$/);
-  if (!match) return 0;
-  const num = parseInt(match[1], 10);
-  const unit = match[2];
-  const multipliers = { d: 86400000, h: 3600000, m: 60000, s: 1000 };
-  return num * (multipliers[unit] || 0);
-}
-
-/**
- * Format age from ISO date to human-readable string
- * @param {string} isoDate - ISO8601 date string
- * @returns {string} Human-readable age like "5m", "2h", "3d"
- */
-function formatAge(isoDate) {
-  if (!isoDate) return 'unknown';
-  const diffMs = Date.now() - new Date(isoDate).getTime();
-  if (diffMs < 0) return 'future';
-  const minutes = Math.floor(diffMs / 60000);
-  if (minutes < 60) return `${minutes}m`;
-  const hours = Math.floor(minutes / 60);
-  if (hours < 24) return `${hours}h`;
-  const days = Math.floor(hours / 24);
-  return `${days}d`;
-}
-
 /**
  * Classify severity from GitHub labels
  * @param {Array} labels - Array of label objects with 'name' field, or strings
@@ -415,6 +384,12 @@ const { handleLogstash } = require('./observe-handler-logstash.cjs');
 // Internal work detection handler
 const { handleInternal } = require('./observe-handler-internal.cjs');
 
+// Upstream tracking handler
+const { handleUpstream } = require('./observe-handler-upstream.cjs');
+
+// Dependency freshness handler
+const { handleDeps } = require('./observe-handler-deps.cjs');
+
 module.exports = {
   handleGitHub,
   handleSentry,
@@ -428,6 +403,10 @@ module.exports = {
   handleLogstash,
   // Internal work detection (quick-168)
   handleInternal,
+  // Upstream tracking
+  handleUpstream,
+  // Dependency freshness
+  handleDeps,
   // Exported for testing
   parseDuration,
   formatAge,

package/bin/observe-render.cjs

@@ -1,8 +1,10 @@
 /**
- * Dual-table renderer for /qgsd:observe
+ * Dual-table renderer for /nf:observe
  * Renders Issues table and Drifts table with error section
  */
 
+const { formatAge } = require('./observe-utils.cjs');
+
 // Severity sort order (lower = higher priority)
 const SEVERITY_ORDER = { error: 0, critical: 0, bug: 1, warning: 2, info: 3 };
 
@@ -15,23 +17,6 @@ function classifySeverity(severity) {
   return SEVERITY_ORDER[severity] ?? 4;
 }
 
-/**
- * Format age from ISO date to human-readable string
- * @param {string} isoDate
- * @returns {string}
- */
-function formatAge(isoDate) {
-  if (!isoDate) return '';
-  const diffMs = Date.now() - new Date(isoDate).getTime();
-  if (diffMs < 0) return 'future';
-  const minutes = Math.floor(diffMs / 60000);
-  if (minutes < 60) return `${minutes}m`;
-  const hours = Math.floor(minutes / 60);
-  if (hours < 24) return `${hours}h`;
-  const days = Math.floor(hours / 24);
-  return `${days}d`;
-}
-
 /**
  * Truncate a string to maxLen, adding "..." if truncated
  * @param {string} str
@@ -79,26 +64,32 @@ function renderObserveOutput(results) {
   }
 
   // Split by issue_type
-  const issues = allItems.filter(item => item.issue_type !== 'drift');
+  const issues = allItems.filter(item => !['drift', 'upstream', 'deps'].includes(item.issue_type));
   const drifts = allItems.filter(item => item.issue_type === 'drift');
+  const upstreams = allItems.filter(item => item.issue_type === 'upstream');
+  const deps = allItems.filter(item => item.issue_type === 'deps');
 
   const totalIssues = issues.length;
   const totalDrifts = drifts.length;
+  const totalUpstreams = upstreams.length;
+  const totalDeps = deps.length;
 
   // Header
-  if (totalIssues === 0 && totalDrifts === 0 && errorResults.length === 0) {
+  if (totalIssues === 0 && totalDrifts === 0 && totalUpstreams === 0 && totalDeps === 0 && errorResults.length === 0) {
     lines.push('');
     lines.push('━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━');
-    lines.push(' QGSD > OBSERVE: All clear — no open issues found');
+    lines.push(' nForma > OBSERVE: All clear — no open issues found');
     lines.push('━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━');
     lines.push(`Sources checked: ${sourceCount}`);
     return lines.join('\n');
   }
 
+  const upstreamNote = totalUpstreams > 0 ? `, ${totalUpstreams} upstream(s)` : '';
+  const depsNote = totalDeps > 0 ? `, ${totalDeps} dep(s)` : '';
   const failNote = errorResults.length > 0 ? `; ${errorResults.length} source(s) failed` : '';
   lines.push('');
   lines.push('━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━');
-  lines.push(` QGSD > OBSERVE: ${totalIssues} issue(s), ${totalDrifts} drift(s) across ${sourceCount} source(s)${failNote}`);
+  lines.push(` nForma > OBSERVE: ${totalIssues} issue(s), ${totalDrifts} drift(s)${upstreamNote}${depsNote} across ${sourceCount} source(s)${failNote}`);
   lines.push('━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━');
 
   // Sort issues by severity then age (newest first)
@@ -153,6 +144,61 @@ function renderObserveOutput(results) {
     lines.push('└─────────────────────────────────────────────────────────────────────┘');
   }
 
+  // Render Upstream table
+  if (upstreams.length > 0) {
+    // Sort: warnings first, then by age (newest first)
+    upstreams.sort((a, b) => {
+      const sevCmp = classifySeverity(a.severity) - classifySeverity(b.severity);
+      if (sevCmp !== 0) return sevCmp;
+      return new Date(b.created_at || 0) - new Date(a.created_at || 0);
+    });
+
+    lines.push('');
+    lines.push('┌──────────────────────────── UPSTREAM ──────────────────────────────┐');
+    lines.push('│ #  │ Title                                    │ Repo    │ Tag │ Age  │');
+    lines.push('├─────────────────────────────────────────────────────────────────────┤');
+
+    for (let i = 0; i < upstreams.length; i++) {
+      const item = upstreams[i];
+      const num = String(i + 1).padStart(2, ' ');
+      const title = pad(truncate(item.title, 40), 40);
+      const repo = pad(truncate((item._upstream?.repo || item.source_label || '').split('/').pop(), 7), 7);
+      const tag = pad(truncate(item._upstream?.tag || `#${item._upstream?.pr || ''}`, 3), 3);
+      const age = pad(item.age || formatAge(item.created_at), 4);
+      lines.push(`│ ${num} │ ${title} │ ${repo} │ ${tag} │ ${age} │`);
+    }
+
+    lines.push('└─────────────────────────────────────────────────────────────────────┘');
+  }
+
+  // Render Dependencies table
+  if (deps.length > 0) {
+    // Sort: vulns first (error), then warnings (major), then info (minor/patch)
+    deps.sort((a, b) => {
+      const sevCmp = classifySeverity(a.severity) - classifySeverity(b.severity);
+      if (sevCmp !== 0) return sevCmp;
+      // Within same severity, sort by package name
+      return (a.title || '').localeCompare(b.title || '');
+    });
+
+    lines.push('');
+    lines.push('┌────────────────────────── DEPENDENCIES ────────────────────────────┐');
+    lines.push('│ #  │ Package                                  │ Bump    │ Sev │ Meta │');
+    lines.push('├─────────────────────────────────────────────────────────────────────┤');
+
+    for (let i = 0; i < deps.length; i++) {
+      const item = deps[i];
+      const num = String(i + 1).padStart(2, ' ');
+      const title = pad(truncate(item.title, 40), 40);
+      const bump = pad(truncate(item._deps?.bumpType || '', 7), 7);
+      const sev = pad(truncate(item.severity || 'info', 3), 3);
+      const meta = pad(truncate(item.meta || '', 4), 4);
+      lines.push(`│ ${num} │ ${title} │ ${bump} │ ${sev} │ ${meta} │`);
+    }
+
+    lines.push('└─────────────────────────────────────────────────────────────────────┘');
+  }
+
   // Render errors section
   if (errorResults.length > 0) {
     lines.push('');

package/bin/observe-utils.cjs

@@ -0,0 +1,37 @@
+/**
+ * Shared utility functions for observe handlers
+ * Canonical source — all observe handlers import from here (OBS-10)
+ */
+
+/**
+ * Parse a duration string like "7d", "24h", "30m" into milliseconds
+ * @param {string} duration - Duration string
+ * @returns {number} Milliseconds (0 for invalid input)
+ */
+function parseDuration(duration) {
+  if (!duration) return 0;
+  const match = String(duration).match(/^(\d+)([dhms])$/);
+  if (!match) return 0;
+  const num = parseInt(match[1], 10);
+  const multipliers = { d: 86400000, h: 3600000, m: 60000, s: 1000 };
+  return num * (multipliers[match[2]] || 0);
+}
+
+/**
+ * Format age from ISO date to human-readable string
+ * @param {string} isoDate - ISO8601 date string
+ * @returns {string} Human-readable age like "5m", "2h", "3d"
+ */
+function formatAge(isoDate) {
+  if (!isoDate) return 'unknown';
+  const diffMs = Date.now() - new Date(isoDate).getTime();
+  if (diffMs < 0) return 'future';
+  const minutes = Math.floor(diffMs / 60000);
+  if (minutes < 60) return `${minutes}m`;
+  const hours = Math.floor(minutes / 60);
+  if (hours < 24) return `${hours}h`;
+  const days = Math.floor(hours / 24);
+  return `${days}d`;
+}
+
+module.exports = { parseDuration, formatAge };