@aiwg/cli 0.0.0-bootstrap.0 → 2026.7.17

package/dist/src/update/checker.mjs

@@ -0,0 +1,396 @@
+/**
+ * Update Checker
+ *
+ * Checks for available updates and prompts the user to update.
+ * - Stable channel: Checks npm registry for newer version
+ * - Edge channel: Checks git remote for new commits
+ *
+ * @module src/update/checker
+ * @version 2024.12.0
+ */
+
+import fs from 'fs/promises';
+import path from 'path';
+import https from 'https';
+import { execSync } from 'child_process';
+import { createInterface } from 'readline';
+import { loadConfig, saveConfig, getChannel, getPackageRoot } from '../channel/manager.mjs';
+
+const NPM_REGISTRY = 'https://registry.npmjs.org/aiwg';
+
+/**
+ * Fetch latest version for a given npm dist-tag
+ * @param {string} distTag - npm dist-tag to resolve (latest, next, nightly)
+ * @returns {Promise<string|null>} Resolved version or null on error
+ */
+async function fetchNpmDistTag(distTag = 'latest') {
+  return new Promise((resolve) => {
+    const request = https.get(NPM_REGISTRY, { timeout: 5000 }, (res) => {
+      if (res.statusCode !== 200) {
+        resolve(null);
+        return;
+      }
+
+      let data = '';
+      res.on('data', (chunk) => { data += chunk; });
+      res.on('end', () => {
+        try {
+          const pkg = JSON.parse(data);
+          resolve(pkg['dist-tags']?.[distTag] || null);
+        } catch {
+          resolve(null);
+        }
+      });
+    });
+
+    request.on('error', () => resolve(null));
+    request.on('timeout', () => {
+      request.destroy();
+      resolve(null);
+    });
+  });
+}
+
+/**
+ * Fetch latest version from npm registry (stable)
+ * @returns {Promise<string|null>} Latest version or null on error
+ */
+async function fetchLatestNpmVersion() {
+  return fetchNpmDistTag('latest');
+}
+
+/**
+ * Check if there are new commits in the git remote (edge channel)
+ * @param {string} edgePath - Path to edge installation
+ * @returns {Promise<boolean>} True if updates available
+ */
+async function checkGitUpdates(edgePath) {
+  try {
+    // Fetch latest without merging
+    execSync('git fetch --quiet', { cwd: edgePath, timeout: 10000 });
+
+    // Check if local is behind remote
+    const localHash = execSync('git rev-parse HEAD', {
+      cwd: edgePath,
+      encoding: 'utf8',
+    }).trim();
+
+    const remoteHash = execSync('git rev-parse origin/main', {
+      cwd: edgePath,
+      encoding: 'utf8',
+    }).trim();
+
+    return localHash !== remoteHash;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Compare CalVer versions
+ * @param {string} current - Current version (e.g., "2024.12.0")
+ * @param {string} latest - Latest version
+ * @returns {boolean} True if latest is newer
+ */
+function isNewerVersion(current, latest) {
+  if (!current || !latest) return false;
+
+  const parseVersion = (v) => {
+    const match = v.match(/^(\d+)\.(\d+)\.(\d+)/);
+    if (!match) return [0, 0, 0];
+    return [parseInt(match[1], 10), parseInt(match[2], 10), parseInt(match[3], 10)];
+  };
+
+  const [cy, cm, cp] = parseVersion(current);
+  const [ly, lm, lp] = parseVersion(latest);
+
+  if (ly > cy) return true;
+  if (ly === cy && lm > cm) return true;
+  if (ly === cy && lm === cm && lp > cp) return true;
+
+  return false;
+}
+
+/**
+ * Prompt user for update confirmation
+ * @param {string} message - Prompt message
+ * @returns {Promise<boolean>} True if user confirms
+ */
+async function promptUpdate(message) {
+  // Skip prompt if not interactive terminal
+  if (!process.stdin.isTTY || !process.stdout.isTTY) {
+    return false;
+  }
+
+  const rl = createInterface({
+    input: process.stdin,
+    output: process.stdout,
+  });
+
+  // Hard timeout so the update prompt cannot hang the CLI. The update check
+  // runs as a background fire-and-forget from bin/aiwg.mjs; if the user isn't
+  // watching the terminal, we silently decline instead of blocking forever.
+  // Override via AIWG_PROMPT_TIMEOUT_MS.
+  const timeoutMs = (() => {
+    const raw = process.env['AIWG_PROMPT_TIMEOUT_MS'];
+    const n = raw ? parseInt(raw, 10) : NaN;
+    return Number.isFinite(n) && n > 0 ? n : 10_000;
+  })();
+
+  return new Promise((resolve) => {
+    let settled = false;
+    const timer = setTimeout(() => {
+      if (settled) return;
+      settled = true;
+      rl.close();
+      resolve(false);
+    }, timeoutMs);
+    timer.unref?.();
+    rl.question(`${message} [y/N]: `, (answer) => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      rl.close();
+      const normalized = answer.toLowerCase().trim();
+      resolve(normalized === 'y' || normalized === 'yes');
+    });
+  });
+}
+
+/**
+ * Check for updates (background, non-blocking)
+ * This is called on every CLI invocation but only checks periodically
+ */
+export async function checkForUpdates() {
+  const config = await loadConfig();
+
+  // Check if enough time has passed since last check
+  const now = Date.now();
+  const lastCheck = config.lastUpdateCheck || 0;
+  const interval = config.updateCheckInterval || 86400000; // 24 hours
+
+  if (now - lastCheck < interval) {
+    // Too soon to check again
+    return;
+  }
+
+  // Update last check time
+  config.lastUpdateCheck = now;
+  await saveConfig(config);
+
+  if (config.channel === 'next') {
+    await checkNextUpdates(config);
+  } else if (config.channel === 'nightly') {
+    await checkNightlyUpdates(config);
+  } else if (config.channel === 'edge') {
+    await checkEdgeUpdates(config);
+  } else {
+    // stable (or unrecognised — treat as stable)
+    await checkStableUpdates(config);
+  }
+}
+
+/**
+ * Check for stable (npm) channel updates
+ */
+async function checkStableUpdates(config) {
+  const packageRoot = getPackageRoot();
+  const packageJsonPath = path.join(packageRoot, 'package.json');
+
+  try {
+    const packageJson = JSON.parse(await fs.readFile(packageJsonPath, 'utf8'));
+    const currentVersion = packageJson.version;
+    const latestVersion = await fetchLatestNpmVersion();
+
+    if (latestVersion && isNewerVersion(currentVersion, latestVersion)) {
+      console.log('');
+      console.log(`A new version of aiwg is available: ${currentVersion} → ${latestVersion}`);
+
+      const shouldUpdate = await promptUpdate('Would you like to update now?');
+
+      if (shouldUpdate) {
+        console.log('');
+        console.log('Updating aiwg...');
+        try {
+          execSync('npm install -g aiwg@latest', { stdio: 'inherit' });
+          console.log('Update complete! Please restart your terminal.');
+        } catch (error) {
+          console.error('Update failed. Run manually: npm install -g aiwg@latest');
+        }
+      } else {
+        console.log('Update skipped. Run `npm install -g aiwg@latest` when ready.');
+      }
+      console.log('');
+    }
+  } catch {
+    // Silently ignore errors during update check
+  }
+}
+
+/**
+ * Check for next (alpha/beta/RC) channel updates
+ */
+async function checkNextUpdates(config) {
+  const packageRoot = getPackageRoot();
+  const packageJsonPath = path.join(packageRoot, 'package.json');
+
+  try {
+    const packageJson = JSON.parse(await fs.readFile(packageJsonPath, 'utf8'));
+    const currentVersion = packageJson.version;
+    const latestVersion = await fetchNpmDistTag('next');
+
+    if (!latestVersion) return;
+
+    if (currentVersion !== latestVersion) {
+      console.log('');
+      console.log(`A new next release is available: ${currentVersion} → ${latestVersion}`);
+
+      const shouldUpdate = await promptUpdate('Would you like to update now?');
+
+      if (shouldUpdate) {
+        console.log('');
+        console.log('Updating aiwg@next...');
+        try {
+          execSync('npm install -g aiwg@next', { stdio: 'inherit' });
+          console.log('Update complete! Please restart your terminal.');
+        } catch {
+          console.error('Update failed. Run manually: npm install -g aiwg@next');
+        }
+      } else {
+        console.log('Update skipped. Run `npm install -g aiwg@next` when ready.');
+      }
+      console.log('');
+    }
+  } catch {
+    // Silently ignore errors during update check
+  }
+}
+
+/**
+ * Check for nightly channel updates
+ */
+async function checkNightlyUpdates(config) {
+  const packageRoot = getPackageRoot();
+  const packageJsonPath = path.join(packageRoot, 'package.json');
+
+  try {
+    const packageJson = JSON.parse(await fs.readFile(packageJsonPath, 'utf8'));
+    const currentVersion = packageJson.version;
+    const latestVersion = await fetchNpmDistTag('nightly');
+
+    if (!latestVersion) return;
+
+    if (currentVersion !== latestVersion) {
+      console.log('');
+      console.log(`A new nightly snapshot is available: ${currentVersion} → ${latestVersion}`);
+
+      const shouldUpdate = await promptUpdate('Would you like to update now?');
+
+      if (shouldUpdate) {
+        console.log('');
+        console.log('Updating aiwg@nightly...');
+        try {
+          execSync('npm install -g aiwg@nightly', { stdio: 'inherit' });
+          console.log('Update complete! Please restart your terminal.');
+        } catch {
+          console.error('Update failed. Run manually: npm install -g aiwg@nightly');
+        }
+      } else {
+        console.log('Update skipped. Run `npm install -g aiwg@nightly` when ready.');
+      }
+      console.log('');
+    }
+  } catch {
+    // Silently ignore errors during update check
+  }
+}
+
+/**
+ * Check for edge (git) channel updates
+ */
+async function checkEdgeUpdates(config) {
+  const hasUpdates = await checkGitUpdates(config.edgePath);
+
+  if (hasUpdates) {
+    console.log('');
+    console.log('New commits available in the main branch.');
+
+    const shouldUpdate = await promptUpdate('Would you like to update now?');
+
+    if (shouldUpdate) {
+      console.log('');
+      console.log('Updating edge installation...');
+      try {
+        execSync('git pull --ff-only', { cwd: config.edgePath, stdio: 'inherit' });
+        console.log('Update complete!');
+      } catch (error) {
+        console.error('Update failed. Run manually:');
+        console.error(`  cd ${config.edgePath} && git pull`);
+      }
+    } else {
+      console.log('Update skipped. Run `aiwg -update` when ready.');
+    }
+    console.log('');
+  }
+}
+
+/**
+ * Force an update check (called by aiwg -update)
+ */
+export async function forceUpdateCheck() {
+  const config = await loadConfig();
+  const packageRoot = getPackageRoot();
+  const packageJsonPath = path.join(packageRoot, 'package.json');
+  const packageJson = JSON.parse(await fs.readFile(packageJsonPath, 'utf8'));
+  const currentVersion = packageJson.version;
+
+  if (config.channel === 'next') {
+    console.log('Checking for updates on next channel...');
+    const latestVersion = await fetchNpmDistTag('next');
+    if (!latestVersion) {
+      console.log('Could not check npm registry. Try: npm install -g aiwg@next');
+      return;
+    }
+    if (currentVersion !== latestVersion) {
+      console.log(`Update available: ${currentVersion} → ${latestVersion}`);
+      console.log('');
+      console.log('Run: npm install -g aiwg@next');
+    } else {
+      console.log(`You are on the latest next release: ${currentVersion}`);
+    }
+  } else if (config.channel === 'nightly') {
+    console.log('Checking for updates on nightly channel...');
+    const latestVersion = await fetchNpmDistTag('nightly');
+    if (!latestVersion) {
+      console.log('Could not check npm registry. Try: npm install -g aiwg@nightly');
+      return;
+    }
+    if (currentVersion !== latestVersion) {
+      console.log(`Update available: ${currentVersion} → ${latestVersion}`);
+      console.log('');
+      console.log('Run: npm install -g aiwg@nightly');
+    } else {
+      console.log(`You are on the latest nightly snapshot: ${currentVersion}`);
+    }
+  } else if (config.channel === 'edge') {
+    const { updateEdge } = await import('../channel/manager.mjs');
+    await updateEdge();
+  } else {
+    // stable
+    console.log('Checking for updates...');
+    const latestVersion = await fetchLatestNpmVersion();
+
+    if (!latestVersion) {
+      console.log('Could not check npm registry. Try: npm install -g aiwg@latest');
+      return;
+    }
+
+    if (isNewerVersion(currentVersion, latestVersion)) {
+      console.log(`Update available: ${currentVersion} → ${latestVersion}`);
+      console.log('');
+      console.log('Run: npm install -g aiwg@latest');
+    } else {
+      console.log(`You are on the latest version: ${currentVersion}`);
+    }
+  }
+}

package/dist/src/update/notifier.mjs

@@ -0,0 +1,235 @@
+/**
+ * AIWG Update Notifier
+ *
+ * Non-blocking update check for the AIWG CLI. Follows the
+ * `update-notifier` / `simple-update-notifier` pattern:
+ *
+ *   1. On CLI invocation, `scheduleBackgroundCheck()` is called from
+ *      `bin/aiwg.mjs`. It spawns a **detached, unref()'d** child Node
+ *      process that runs this file with `--check` and writes the result
+ *      to `~/.aiwg/update-notifier.json`. The child exits immediately
+ *      after writing; the parent never waits on it.
+ *
+ *   2. On the *next* invocation, `maybePrintNotice()` reads the cache
+ *      and prints a single-line "update available" message to stderr.
+ *      The user's current command is never delayed by a network call.
+ *
+ * The update check honours `NO_UPDATE_NOTIFIER`, `CI`, the isInteractive()
+ * helper, and `--no-update-check`. In all of those cases the check is
+ * skipped entirely.
+ *
+ * Phase 3 of the CLI Stabilization Epic (#920). Replaces the synchronous
+ * `checkForUpdates()` + hand-rolled prompt in `checker.mjs` that held the
+ * event loop open after the command completed.
+ *
+ * @module src/update/notifier
+ */
+
+import https from 'https';
+import path from 'path';
+import os from 'os';
+import { readFileSync, writeFileSync, existsSync, mkdirSync } from 'fs';
+import { spawn } from 'child_process';
+import { fileURLToPath } from 'url';
+
+const CACHE_DIR = path.join(os.homedir(), '.aiwg');
+const CACHE_FILE = path.join(CACHE_DIR, 'update-notifier.json');
+
+/**
+ * Minimum time between update checks (24 hours). Checked via the
+ * `lastCheckAt` timestamp in the cache file.
+ */
+const CHECK_INTERVAL_MS = 24 * 60 * 60 * 1000;
+
+/**
+ * Hard timeout for the npm registry HTTPS request. Keeps the spawned
+ * background child from lingering on slow networks.
+ */
+const NETWORK_TIMEOUT_MS = 10_000;
+
+/**
+ * Read an env var and return true iff it's set to a truthy value.
+ */
+function envFlag(name) {
+  const v = process.env[name];
+  if (!v) return false;
+  return v !== '0' && v.toLowerCase() !== 'false';
+}
+
+/**
+ * True iff update checking is currently disabled by env / CI conventions.
+ */
+function isDisabled() {
+  if (envFlag('NO_UPDATE_NOTIFIER')) return true;
+  if (envFlag('AIWG_NO_UPDATE_CHECK')) return true;
+  if (envFlag('CI')) return true;
+  if (envFlag('GITHUB_ACTIONS')) return true;
+  if (envFlag('GITLAB_CI')) return true;
+  // Non-interactive terminals shouldn't get a notice they can't act on.
+  if (!process.stdout.isTTY) return true;
+  return false;
+}
+
+/**
+ * Read the update-notifier cache. Returns null if absent or malformed.
+ */
+function readCache() {
+  if (!existsSync(CACHE_FILE)) return null;
+  try {
+    return JSON.parse(readFileSync(CACHE_FILE, 'utf-8'));
+  } catch {
+    return null;
+  }
+}
+
+function writeCache(data) {
+  try {
+    mkdirSync(CACHE_DIR, { recursive: true });
+    writeFileSync(CACHE_FILE, JSON.stringify(data, null, 2) + '\n', 'utf-8');
+  } catch {
+    // Best-effort — update-notifier failures are never fatal.
+  }
+}
+
+/**
+ * Compare two CalVer/semver-style versions. Returns true iff `latest` is
+ * newer than `current`. Cheap, no full semver parsing.
+ */
+function isNewer(current, latest) {
+  if (!current || !latest || current === latest) return false;
+  const parse = (v) => {
+    const match = String(v).match(/^(\d+)\.(\d+)\.(\d+)/);
+    if (!match) return [0, 0, 0];
+    return [parseInt(match[1], 10), parseInt(match[2], 10), parseInt(match[3], 10)];
+  };
+  const [cy, cm, cp] = parse(current);
+  const [ly, lm, lp] = parse(latest);
+  if (ly > cy) return true;
+  if (ly === cy && lm > cm) return true;
+  if (ly === cy && lm === cm && lp > cp) return true;
+  return false;
+}
+
+/**
+ * Fetch the latest published version for the `latest` dist-tag from npm.
+ * Resolves to `null` on error or timeout.
+ */
+function fetchLatestVersion() {
+  return new Promise((resolve) => {
+    const req = https.get(
+      'https://registry.npmjs.org/aiwg',
+      { timeout: NETWORK_TIMEOUT_MS },
+      (res) => {
+        if (res.statusCode !== 200) {
+          resolve(null);
+          return;
+        }
+        let data = '';
+        res.on('data', (chunk) => { data += chunk; });
+        res.on('end', () => {
+          try {
+            const pkg = JSON.parse(data);
+            resolve(pkg['dist-tags']?.latest ?? null);
+          } catch {
+            resolve(null);
+          }
+        });
+      },
+    );
+    req.on('error', () => resolve(null));
+    req.on('timeout', () => {
+      req.destroy();
+      resolve(null);
+    });
+  });
+}
+
+/**
+ * Read current CLI version from the package.json at `packageRoot`.
+ */
+function readCurrentVersion(packageRoot) {
+  try {
+    const pkgPath = path.join(packageRoot, 'package.json');
+    const pkg = JSON.parse(readFileSync(pkgPath, 'utf-8'));
+    return pkg.version;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Run the actual update check and write the cache file. Invoked by the
+ * spawned background child via `node src/update/notifier.mjs --check`.
+ */
+async function runCheck(packageRoot) {
+  const currentVersion = readCurrentVersion(packageRoot);
+  const latestVersion = await fetchLatestVersion();
+  writeCache({
+    lastCheckAt: new Date().toISOString(),
+    current: currentVersion,
+    latest: latestVersion,
+    hasUpdate: !!(currentVersion && latestVersion && isNewer(currentVersion, latestVersion)),
+  });
+}
+
+/**
+ * Schedule a background update check if one hasn't run in the last
+ * CHECK_INTERVAL_MS. Non-blocking: spawns a detached child process and
+ * returns immediately. The parent must not wait on the child.
+ *
+ * Called exactly once per CLI invocation from `bin/aiwg.mjs`.
+ */
+export function scheduleBackgroundCheck(packageRoot) {
+  if (isDisabled()) return;
+
+  const cache = readCache();
+  if (cache?.lastCheckAt) {
+    const age = Date.now() - new Date(cache.lastCheckAt).getTime();
+    if (age < CHECK_INTERVAL_MS) return; // recent enough — skip
+  }
+
+  try {
+    const entry = fileURLToPath(import.meta.url);
+    const child = spawn(
+      process.execPath,
+      [entry, '--check', '--package-root', packageRoot],
+      {
+        detached: true,
+        stdio: 'ignore',
+        env: { ...process.env, AIWG_UPDATE_NOTIFIER_CHILD: '1' },
+      },
+    );
+    // Unref so the parent can exit without waiting for the child. This is
+    // the crucial detail that prevents the "command hangs for 5 minutes"
+    // symptom we had before #918.
+    child.unref();
+  } catch {
+    // Spawn failures are non-fatal; the next invocation will retry.
+  }
+}
+
+/**
+ * If the cache indicates an update is available AND the current terminal
+ * is interactive, print a single-line notice to stderr. Never prompts.
+ * Safe to call unconditionally from `bin/aiwg.mjs` — gated by isDisabled().
+ */
+export function maybePrintNotice() {
+  if (isDisabled()) return;
+  const cache = readCache();
+  if (!cache?.hasUpdate || !cache.current || !cache.latest) return;
+  // One-line, non-intrusive. Users who want to update run `aiwg update`.
+  const msg = `aiwg: update available ${cache.current} → ${cache.latest} (run: npm install -g aiwg)`;
+  process.stderr.write(`\n${msg}\n`);
+}
+
+// ── Child-process entry ────────────────────────────────────────────────
+
+// If invoked with `--check`, act as the background-child worker.
+if (process.argv.includes('--check')) {
+  const rootIdx = process.argv.indexOf('--package-root');
+  const packageRoot = rootIdx >= 0 ? process.argv[rootIdx + 1] : process.cwd();
+  runCheck(packageRoot).catch(() => {
+    // Swallow all errors — the background child must never write to stderr.
+    process.exit(0);
+  });
+}