@iflow-mcp/jkheadley-instar 0.26.2

package/scripts/check-upgrade-guide.js

@@ -0,0 +1,373 @@
+#!/usr/bin/env node
+/**
+ * Pre-publish upgrade guide check + finalization.
+ *
+ * Every release must ship with an upgrade guide so agents understand
+ * what changed and can relay meaningful context to users.
+ *
+ * This script does TWO things:
+ *   1. VALIDATES the guide exists, is well-formed, and has required sections
+ *   2. FINALIZES the guide by renaming NEXT.md → {version}.md
+ *      (the "CI rename step" that was previously missing)
+ *
+ * After finalization, a fresh NEXT.md template is created so the NEXT
+ * publish is blocked until new content is written.
+ *
+ * Workflow:
+ *   1. Developer writes `upgrades/NEXT.md` alongside code changes
+ *   2. Version is bumped in package.json
+ *   3. `npm publish` triggers `prepublishOnly` which runs this script
+ *   4. Script validates NEXT.md → renames to {version}.md → creates template
+ *   5. Published package contains the versioned guide
+ *   6. Agent's UpgradeGuideProcessor finds the versioned file and delivers it
+ *   7. UpgradeNotifyManager spawns a session to notify the user
+ *
+ * Required sections in every guide:
+ *   - "## What Changed" — technical description for the agent
+ *   - "## What to Tell Your User" — user-facing narrative the agent relays
+ *   - "## Summary of New Capabilities" — concise list for MEMORY.md
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const ROOT = path.resolve(__dirname, '..');
+
+const pkg = JSON.parse(fs.readFileSync(path.join(ROOT, 'package.json'), 'utf-8'));
+const version = pkg.version;
+const guidePath = path.join(ROOT, 'upgrades', `${version}.md`);
+const nextPath = path.join(ROOT, 'upgrades', 'NEXT.md');
+const guideExists = fs.existsSync(guidePath);
+const nextExists = fs.existsSync(nextPath);
+
+// Required sections for a well-formed guide
+const REQUIRED_SECTIONS = [
+  '## What Changed',
+  '## What to Tell Your User',
+  '## Summary of New Capabilities',
+];
+
+const MIN_LENGTH = 200;
+
+// Template for a fresh NEXT.md after finalization
+const NEXT_TEMPLATE = `# Upgrade Guide — vNEXT
+
+<!-- bump: patch -->
+<!-- Valid values: patch, minor, major -->
+<!-- patch = bug fixes, refactors, test additions, doc updates -->
+<!-- minor = new features, new APIs, new capabilities (backwards-compatible) -->
+<!-- major = breaking changes to existing APIs or behavior -->
+
+## What Changed
+
+<!-- Describe what changed technically. What new features, APIs, behavioral changes? -->
+<!-- Write this for the AGENT — they need to understand the system deeply. -->
+
+## What to Tell Your User
+
+<!-- Write talking points the agent should relay to their user. -->
+<!-- This should be warm, conversational, user-facing — not a changelog. -->
+<!-- Focus on what THEY can now do, not internal plumbing. -->
+<!--                                                                    -->
+<!-- PROHIBITED in this section (will fail validation):                 -->
+<!--   camelCase config keys: silentReject, maxRetries, telegramNotify -->
+<!--   Inline code backtick references like silentReject: false        -->
+<!--   Fenced code blocks                                              -->
+<!--   Instructions to edit files or run commands                      -->
+<!--                                                                    -->
+<!-- CORRECT style: "I can turn that on for you" not "set X to false"  -->
+<!-- The agent relays this to their user — keep it human.              -->
+
+- **[Feature name]**: "[Brief, friendly description of what this means for the user]"
+
+## Summary of New Capabilities
+
+| Capability | How to Use |
+|-----------|-----------|
+| [Capability] | [Endpoint, command, or "automatic"] |
+`;
+
+/**
+ * Validate a guide file and return any issues found.
+ */
+function validateGuide(filePath) {
+  const content = fs.readFileSync(filePath, 'utf-8');
+  const issues = [];
+
+  for (const section of REQUIRED_SECTIONS) {
+    if (!content.includes(section)) {
+      issues.push(`missing "${section}" section`);
+    }
+  }
+
+  if (content.length < MIN_LENGTH) {
+    issues.push(`guide is too short (${content.length} chars, minimum ${MIN_LENGTH}) — probably incomplete`);
+  }
+
+  // Check for template placeholders that were never filled in
+  if (content.includes('<!-- Describe what changed')) {
+    issues.push(`"What Changed" section still contains template placeholder — fill it in`);
+  }
+  if (content.includes('[Feature name]') || content.includes('[Brief, friendly description')) {
+    issues.push(`"What to Tell Your User" section still contains template placeholder — fill it in`);
+  }
+  if (content.includes('[Capability]') && content.includes('[Endpoint, command')) {
+    issues.push(`"Summary of New Capabilities" section still contains template placeholder — fill it in`);
+  }
+
+  // Validate "What to Tell Your User" section for technical leakage.
+  // This section is relayed verbatim to users — it must be conversational, not a config reference.
+  const userSectionMatch = content.match(/## What to Tell Your User([\s\S]*?)(?:##|$)/);
+  if (userSectionMatch) {
+    const userSection = userSectionMatch[1];
+
+    // Detect camelCase config key references (e.g. silentReject, maxRetries, telegramNotify)
+    const camelCaseConfigKey = /\b[a-z]+[A-Z][a-zA-Z]+\s*(?::|=)/.test(userSection);
+    if (camelCaseConfigKey) {
+      issues.push(
+        `"What to Tell Your User" contains a camelCase config key reference (e.g. "silentReject: false"). ` +
+        `Users should never be told to edit config directly. ` +
+        `Rephrase conversationally: "I can turn that on for you" not "set silentReject: false".`
+      );
+    }
+
+    // Detect inline code blocks — config syntax, CLI commands, file paths
+    const hasInlineCode = /`[^`]+`/.test(userSection);
+    if (hasInlineCode) {
+      issues.push(
+        `"What to Tell Your User" contains inline code (\`...\`). ` +
+        `Remove code formatting — user-facing language should be plain and conversational.`
+      );
+    }
+
+    // Detect fenced code blocks
+    if (/```/.test(userSection)) {
+      issues.push(
+        `"What to Tell Your User" contains a fenced code block. ` +
+        `This section is for user-facing narrative — move technical examples to "What Changed".`
+      );
+    }
+  }
+
+  return issues;
+}
+
+/**
+ * Parse the declared bump type from a guide's <!-- bump: TYPE --> comment.
+ * Returns 'patch' | 'minor' | 'major' | null.
+ */
+function parseBumpType(content) {
+  const match = /<!--\s*bump:\s*(patch|minor|major)\s*-->/.exec(content);
+  return match ? match[1] : null;
+}
+
+/**
+ * Determine what kind of version bump actually happened
+ * by comparing the new version against the latest published version.
+ */
+function detectActualBump(newVersion, latestPublished) {
+  if (!latestPublished) return null; // Can't determine
+
+  const [newMaj, newMin, newPatch] = newVersion.split('.').map(Number);
+  const [pubMaj, pubMin, pubPatch] = latestPublished.split('.').map(Number);
+
+  if (newMaj > pubMaj) return 'major';
+  if (newMin > pubMin) return 'minor';
+  if (newPatch > pubPatch) return 'patch';
+  return null; // Same or downgrade
+}
+
+/**
+ * Get the latest published version from the upgrades/ directory.
+ * This is the highest versioned guide file, which approximates the last published version.
+ */
+function getLatestPublishedVersion() {
+  if (!fs.existsSync(upgradesDir)) return null;
+
+  const versions = fs.readdirSync(upgradesDir)
+    .map(f => /^(\d+)\.(\d+)\.(\d+)\.md$/.exec(f))
+    .filter(Boolean)
+    .map(m => ({ str: `${m[1]}.${m[2]}.${m[3]}`, parts: [+m[1], +m[2], +m[3]] }))
+    .filter(v => v.str !== version) // Exclude current version — we want the PREVIOUS latest
+    .sort((a, b) => {
+      for (let i = 0; i < 3; i++) {
+        if (a.parts[i] !== b.parts[i]) return a.parts[i] - b.parts[i];
+      }
+      return 0;
+    });
+
+  return versions.length > 0 ? versions[versions.length - 1].str : null;
+}
+
+/**
+ * Validate that the declared bump type matches the actual version change.
+ * Returns warnings (not errors) — advisory, not blocking.
+ */
+function validateBumpType(content) {
+  const warnings = [];
+  const declaredBump = parseBumpType(content);
+
+  if (!declaredBump) {
+    warnings.push('No <!-- bump: TYPE --> declaration found. Add one (patch, minor, or major) to declare the scope of changes.');
+    return warnings;
+  }
+
+  const latestPublished = getLatestPublishedVersion();
+  if (!latestPublished) return warnings; // Can't validate without history
+
+  const actualBump = detectActualBump(version, latestPublished);
+
+  if (!actualBump) return warnings; // Same version or can't determine
+
+  if (declaredBump === 'minor' && actualBump === 'patch') {
+    warnings.push(
+      `Guide declares "bump: minor" but version ${version} is only a PATCH bump from ${latestPublished}.` +
+      ` New features and APIs should use a minor version bump (e.g., npm version minor).`
+    );
+  } else if (declaredBump === 'major' && actualBump !== 'major') {
+    warnings.push(
+      `Guide declares "bump: major" but version ${version} is not a major bump from ${latestPublished}.` +
+      ` Breaking changes should use a major version bump (e.g., npm version major).`
+    );
+  } else if (declaredBump === 'patch' && actualBump === 'minor') {
+    // This is fine — minor bump for a patch is conservative, not wrong
+  }
+
+  // The key enforcement: if the content describes new features but declares "patch"
+  const hasNewFeatures = /new (api|endpoint|feature|command|capability)/i.test(content) ||
+    /\bPOST\b.*\/\w+/.test(content) ||
+    /\bGET\b.*\/\w+/.test(content);
+
+  if (declaredBump === 'patch' && hasNewFeatures && actualBump === 'patch') {
+    warnings.push(
+      `Guide declares "bump: patch" but appears to describe new features/APIs.` +
+      ` New capabilities should be a MINOR version bump. Consider: npm version minor`
+    );
+  }
+
+  return warnings;
+}
+
+/**
+ * Finalize NEXT.md → {version}.md and create fresh template.
+ */
+function finalizeGuide() {
+  // Rename NEXT.md to versioned file
+  fs.renameSync(nextPath, guidePath);
+  console.log(`  Finalized: NEXT.md → ${version}.md`);
+
+  // Update the H1 header to include the actual version
+  let content = fs.readFileSync(guidePath, 'utf-8');
+  content = content.replace(/^# Upgrade Guide — vNEXT$/m, `# Upgrade Guide — v${version}`);
+  fs.writeFileSync(guidePath, content);
+
+  // Create fresh NEXT.md template for the next release
+  fs.writeFileSync(nextPath, NEXT_TEMPLATE);
+  console.log(`  Created fresh NEXT.md template for next release`);
+}
+
+// ── Report ──────────────────────────────────────────────────────────
+
+console.log(`\n  Upgrade Guide Check — v${version}`);
+console.log(`  ${'─'.repeat(40)}`);
+console.log(`  Guide (${version}.md): ${guideExists ? 'YES' : 'NO'}`);
+console.log(`  NEXT.md fallback:     ${nextExists ? 'YES' : 'NO'}`);
+
+// Validate all existing guides (informational — doesn't block)
+const upgradesDir = path.join(ROOT, 'upgrades');
+let malformedGuides = [];
+
+if (fs.existsSync(upgradesDir)) {
+  const guideFiles = fs.readdirSync(upgradesDir).filter(f => f.endsWith('.md') && f !== 'NEXT.md');
+  for (const file of guideFiles) {
+    const issues = validateGuide(path.join(upgradesDir, file));
+    if (issues.length > 0) {
+      malformedGuides.push({ file, issues });
+    }
+  }
+}
+
+if (malformedGuides.length > 0) {
+  console.log(`\n  Warning: ${malformedGuides.length} existing guide(s) have issues:`);
+  for (const { file, issues } of malformedGuides) {
+    console.log(`    ${file}: ${issues.join(', ')}`);
+  }
+}
+
+// ── Enforce ─────────────────────────────────────────────────────────
+
+let exitCode = 0;
+
+if (guideExists) {
+  // Version-specific guide already exists (manually created or previously finalized)
+  const issues = validateGuide(guidePath);
+  if (issues.length > 0) {
+    console.log(`\n  ERROR: Guide for v${version} exists but is malformed:`);
+    for (const issue of issues) {
+      console.log(`    - ${issue}`);
+    }
+    exitCode = 1;
+  } else {
+    console.log(`\n  ✓ Upgrade guide validated for v${version}.`);
+    // Advisory: check version bump type
+    const content = fs.readFileSync(guidePath, 'utf-8');
+    const bumpWarnings = validateBumpType(content);
+    if (bumpWarnings.length > 0) {
+      console.log(`\n  ⚠ Version bump advisory:`);
+      for (const w of bumpWarnings) {
+        console.log(`    ${w}`);
+      }
+    }
+  }
+} else if (nextExists) {
+  // NEXT.md exists — validate it, then finalize (rename → version file)
+  const issues = validateGuide(nextPath);
+  if (issues.length > 0) {
+    console.log(`\n  ERROR: NEXT.md exists but is malformed:`);
+    for (const issue of issues) {
+      console.log(`    - ${issue}`);
+    }
+    console.log(`\n  Fix the issues above before publishing.`);
+    exitCode = 1;
+  } else {
+    // Check version bump type BEFORE finalizing (advisory, not blocking)
+    const content = fs.readFileSync(nextPath, 'utf-8');
+    const bumpWarnings = validateBumpType(content);
+
+    // Validation passed — finalize the guide
+    finalizeGuide();
+    console.log(`\n  ✓ Upgrade guide finalized and validated for v${version}.`);
+    console.log(`  The published package will include upgrades/${version}.md`);
+    console.log(`  Agents will receive this guide on their next update.`);
+
+    if (bumpWarnings.length > 0) {
+      console.log(`\n  ⚠ Version bump advisory:`);
+      for (const w of bumpWarnings) {
+        console.log(`    ${w}`);
+      }
+      console.log(`\n  Consider aborting and re-versioning if the bump type is wrong.`);
+      console.log(`  Semver policy: patch = fixes, minor = features, major = breaking`);
+    }
+  }
+} else {
+  // No guide at all — block the publish
+  console.log(`\n  ERROR: No upgrade guide found for v${version}.`);
+  console.log(`  Every release must include an upgrade guide so agents understand what changed.`);
+  console.log(`\n  Create: upgrades/NEXT.md`);
+  console.log(`  Required sections:`);
+  for (const section of REQUIRED_SECTIONS) {
+    console.log(`    - ${section}`);
+  }
+  console.log(`\n  The guide should tell the story of what changed, how it improves the`);
+  console.log(`  user's experience, and what it means for the agent. This is how agents`);
+  console.log(`  learn about updates and relay meaningful context to their users.`);
+  console.log(`\n  Tip: Write the guide WHILE you're building the feature, not after.`);
+  console.log(`  The "What to Tell Your User" section is especially important — it's`);
+  console.log(`  the narrative the agent will relay to their human.`);
+  exitCode = 1;
+}
+
+console.log('');
+process.exit(exitCode);

package/scripts/collect-metrics.py

@@ -0,0 +1,248 @@
+#!/usr/bin/env python3
+"""
+Instar Telemetry Collector — Tracks npm downloads, GitHub metrics, and stores
+historical data for trend analysis.
+
+Collects:
+  - npm download stats (daily, weekly, monthly)
+  - GitHub repo stats (stars, forks, clones, views, issues)
+  - Computed trends (week-over-week changes)
+
+Outputs:
+  - Appends snapshot to {state_dir}/telemetry.jsonl
+  - Writes latest summary to {state_dir}/telemetry-latest.json
+  - Prints human-readable summary to stdout
+
+Usage:
+  python3 scripts/collect-metrics.py [--state-dir DIR] [--json] [--quiet]
+"""
+
+import argparse
+import json
+import os
+import subprocess
+import sys
+from datetime import datetime, timedelta, timezone
+from pathlib import Path
+
+DEFAULT_STATE_DIR = os.path.expanduser("~/.instar/telemetry")
+
+
+def run_cmd(cmd, timeout=30):
+    """Run a shell command and return stdout, or None on failure."""
+    try:
+        result = subprocess.run(cmd, capture_output=True, text=True, timeout=timeout)
+        if result.returncode == 0:
+            return result.stdout.strip()
+        return None
+    except (subprocess.TimeoutExpired, FileNotFoundError):
+        return None
+
+
+def fetch_npm_downloads():
+    """Fetch npm download stats for the 'instar' package."""
+    today = datetime.now(timezone.utc).strftime("%Y-%m-%d")
+
+    ranges = {
+        "last_day": "last-day",
+        "last_week": "last-week",
+        "last_month": "last-month",
+    }
+
+    stats = {}
+    for key, period in ranges.items():
+        raw = run_cmd(["curl", "-sf", f"https://api.npmjs.org/downloads/point/{period}/instar"])
+        if raw:
+            try:
+                data = json.loads(raw)
+                stats[key] = data.get("downloads", 0)
+            except json.JSONDecodeError:
+                stats[key] = None
+        else:
+            stats[key] = None
+
+    # Also get daily breakdown for last 7 days
+    week_ago = (datetime.now(timezone.utc) - timedelta(days=7)).strftime("%Y-%m-%d")
+    raw = run_cmd(["curl", "-sf", f"https://api.npmjs.org/downloads/range/{week_ago}:{today}/instar"])
+    if raw:
+        try:
+            data = json.loads(raw)
+            stats["daily_breakdown"] = [
+                {"date": d["day"], "downloads": d["downloads"]}
+                for d in data.get("downloads", [])
+            ]
+        except json.JSONDecodeError:
+            stats["daily_breakdown"] = []
+
+    return stats
+
+
+def fetch_github_metrics():
+    """Fetch GitHub repo stats using gh CLI."""
+    metrics = {}
+
+    # Repo stats
+    raw = run_cmd(["gh", "api", "repos/SageMindAI/instar", "--jq",
+                    '{stars: .stargazers_count, forks: .forks_count, open_issues: .open_issues_count, watchers: .subscribers_count}'])
+    if raw:
+        try:
+            metrics["repo"] = json.loads(raw)
+        except json.JSONDecodeError:
+            metrics["repo"] = None
+
+    # Clone traffic (last 14 days)
+    raw = run_cmd(["gh", "api", "repos/SageMindAI/instar/traffic/clones", "--jq",
+                    '{total: .count, unique: .uniques}'])
+    if raw:
+        try:
+            metrics["clones_14d"] = json.loads(raw)
+        except json.JSONDecodeError:
+            metrics["clones_14d"] = None
+
+    # View traffic (last 14 days)
+    raw = run_cmd(["gh", "api", "repos/SageMindAI/instar/traffic/views", "--jq",
+                    '{total: .count, unique: .uniques}'])
+    if raw:
+        try:
+            metrics["views_14d"] = json.loads(raw)
+        except json.JSONDecodeError:
+            metrics["views_14d"] = None
+
+    # Referral sources
+    raw = run_cmd(["gh", "api", "repos/SageMindAI/instar/traffic/popular/referrers"])
+    if raw:
+        try:
+            referrers = json.loads(raw)
+            metrics["top_referrers"] = [
+                {"source": r["referrer"], "count": r["count"], "uniques": r["uniques"]}
+                for r in referrers[:5]
+            ]
+        except json.JSONDecodeError:
+            metrics["top_referrers"] = []
+
+    return metrics
+
+
+def compute_trends(state_dir):
+    """Compare current metrics to previous snapshots for trend detection."""
+    history_file = Path(state_dir) / "telemetry.jsonl"
+    if not history_file.exists():
+        return None
+
+    # Read last 7 entries
+    lines = history_file.read_text().strip().split("\n")
+    recent = []
+    for line in lines[-7:]:
+        try:
+            recent.append(json.loads(line))
+        except json.JSONDecodeError:
+            continue
+
+    if len(recent) < 2:
+        return None
+
+    prev = recent[-2] if len(recent) >= 2 else None
+    week_ago = recent[0] if len(recent) >= 7 else recent[0]
+
+    trends = {}
+    if prev:
+        prev_npm = prev.get("npm", {}).get("last_day")
+        trends["npm_day_prev"] = prev_npm
+
+    if week_ago:
+        week_npm = week_ago.get("npm", {}).get("last_week")
+        trends["npm_week_prev"] = week_npm
+
+    return trends
+
+
+def save_snapshot(snapshot, state_dir):
+    """Append snapshot to JSONL history and write latest summary."""
+    state_path = Path(state_dir)
+    state_path.mkdir(parents=True, exist_ok=True)
+
+    # Append to history
+    history_file = state_path / "telemetry.jsonl"
+    with open(history_file, "a") as f:
+        f.write(json.dumps(snapshot) + "\n")
+
+    # Write latest
+    latest_file = state_path / "telemetry-latest.json"
+    with open(latest_file, "w") as f:
+        json.dump(snapshot, f, indent=2)
+
+
+def format_summary(snapshot):
+    """Format a human-readable summary."""
+    lines = []
+    ts = snapshot.get("timestamp", "unknown")
+    lines.append(f"Instar Telemetry Snapshot — {ts}")
+    lines.append("=" * 50)
+
+    npm = snapshot.get("npm", {})
+    lines.append(f"\nnpm Downloads:")
+    lines.append(f"  Last 24h:  {npm.get('last_day', '?'):>8,}")
+    lines.append(f"  Last 7d:   {npm.get('last_week', '?'):>8,}")
+    lines.append(f"  Last 30d:  {npm.get('last_month', '?'):>8,}")
+
+    gh = snapshot.get("github", {})
+    repo = gh.get("repo", {})
+    if repo:
+        lines.append(f"\nGitHub Repo:")
+        lines.append(f"  Stars:     {repo.get('stars', '?'):>8}")
+        lines.append(f"  Forks:     {repo.get('forks', '?'):>8}")
+        lines.append(f"  Issues:    {repo.get('open_issues', '?'):>8}")
+
+    clones = gh.get("clones_14d", {})
+    if clones:
+        lines.append(f"\nGit Clones (14d):")
+        lines.append(f"  Total:     {clones.get('total', '?'):>8,}")
+        lines.append(f"  Unique:    {clones.get('unique', '?'):>8,}")
+
+    views = gh.get("views_14d", {})
+    if views:
+        lines.append(f"\nPage Views (14d):")
+        lines.append(f"  Total:     {views.get('total', '?'):>8}")
+        lines.append(f"  Unique:    {views.get('unique', '?'):>8}")
+
+    referrers = gh.get("top_referrers", [])
+    if referrers:
+        lines.append(f"\nTop Referrers:")
+        for r in referrers:
+            lines.append(f"  {r['source']:<25} {r['count']:>5} ({r['uniques']} unique)")
+
+    return "\n".join(lines)
+
+
+def main():
+    parser = argparse.ArgumentParser(description="Collect Instar telemetry metrics")
+    parser.add_argument("--state-dir", default=DEFAULT_STATE_DIR, help="Directory for telemetry data")
+    parser.add_argument("--json", action="store_true", help="Output JSON instead of human-readable")
+    parser.add_argument("--quiet", action="store_true", help="No stdout output (just save)")
+    args = parser.parse_args()
+
+    snapshot = {
+        "timestamp": datetime.now(timezone.utc).isoformat(),
+        "collector_version": "1.0.0",
+    }
+
+    # Collect
+    snapshot["npm"] = fetch_npm_downloads()
+    snapshot["github"] = fetch_github_metrics()
+    snapshot["trends"] = compute_trends(args.state_dir)
+
+    # Save
+    save_snapshot(snapshot, args.state_dir)
+
+    # Output
+    if not args.quiet:
+        if args.json:
+            print(json.dumps(snapshot, indent=2))
+        else:
+            print(format_summary(snapshot))
+
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())