m365-agent-cli 1.2.0

package/src/lib/git-commit.ts

@@ -0,0 +1,4 @@
+/**
+ * Commit SHA for this build. Generated by scripts/embed-git-sha.mjs — do not edit by hand.
+ */
+export const COMMIT_SHA = '2475a461ca1905fe89371a3d4232b199e4d7cb33';

package/src/lib/glitchtip-eligibility.ts

@@ -0,0 +1,220 @@
+/**
+ * Gate GlitchTip: only when this install matches the latest npm release and the embedded
+ * commit matches the GitHub tag v{version} (see docs/GLITCHTIP.md).
+ */
+import { readFileSync } from 'node:fs';
+import { readFile } from 'node:fs/promises';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { atomicWriteUtf8File } from './atomic-write.js';
+import { COMMIT_SHA } from './git-commit.js';
+import { getPackageJsonPath, getPackageVersion } from './package-info.js';
+
+const NPM_PKG = 'm365-agent-cli';
+/** How long to cache npm + GitHub tag lookups (avoid hammering registries on every invocation). */
+const CACHE_TTL_MS = 60 * 60 * 1000;
+const FETCH_TIMEOUT_MS = 12_000;
+
+export interface GlitchTipEligibility {
+  ok: boolean;
+  reason?: string;
+}
+
+interface EligibilityCache {
+  fetchedAt: number;
+  npmLatest: string;
+  /** Resolved commit SHA for tag v{npmLatest} */
+  tagCommitSha: string | null;
+}
+
+function parseGithubRepo(repoUrl: string | undefined): { owner: string; repo: string } | null {
+  if (!repoUrl) return null;
+  const m = repoUrl.match(/github\.com[/:]([^/]+)\/([^/.]+)/i);
+  if (!m) return null;
+  return { owner: m[1], repo: m[2] };
+}
+
+async function readGithubCoords(): Promise<{ owner: string; repo: string } | null> {
+  const raw = readFileSync(getPackageJsonPath(), 'utf8');
+  const j = JSON.parse(raw) as { repository?: { url?: string } };
+  return parseGithubRepo(j.repository?.url);
+}
+
+function cacheFile(): string {
+  return join(homedir(), '.config', 'm365-agent-cli', 'cache', 'glitchtip-eligibility.json');
+}
+
+function assertEligibilityCache(data: unknown): EligibilityCache {
+  if (!data || typeof data !== 'object') throw new Error('invalid eligibility cache');
+  const o = data as Record<string, unknown>;
+  if (typeof o.fetchedAt !== 'number' || !Number.isFinite(o.fetchedAt)) throw new Error('invalid eligibility cache');
+  if (typeof o.npmLatest !== 'string' || o.npmLatest.trim().length < 3 || o.npmLatest.length > 80) {
+    throw new Error('invalid eligibility cache');
+  }
+  const sha = o.tagCommitSha;
+  if (sha !== null && (typeof sha !== 'string' || !/^[0-9a-f]{40}$/i.test(sha))) {
+    throw new Error('invalid eligibility cache');
+  }
+  return {
+    fetchedAt: o.fetchedAt,
+    npmLatest: o.npmLatest.trim(),
+    tagCommitSha: sha
+  };
+}
+
+async function loadCache(): Promise<EligibilityCache | null> {
+  try {
+    const raw = await readFile(cacheFile(), 'utf8');
+    return assertEligibilityCache(JSON.parse(raw));
+  } catch {
+    return null;
+  }
+}
+
+async function saveCache(c: EligibilityCache): Promise<void> {
+  const safe = assertEligibilityCache(c);
+  await atomicWriteUtf8File(cacheFile(), JSON.stringify(safe, null, 2), 0o600);
+}
+
+function assertEligibilityFetchUrl(url: string): URL {
+  const u = new URL(url);
+  if (u.protocol !== 'https:') throw new Error('unsupported URL');
+  const host = u.hostname;
+  if (host !== 'registry.npmjs.org' && host !== 'api.github.com') {
+    throw new Error('unsupported URL');
+  }
+  return u;
+}
+
+async function fetchJson<T>(url: string): Promise<{ ok: boolean; data?: T; status: number }> {
+  let href: string;
+  try {
+    href = assertEligibilityFetchUrl(url).toString();
+  } catch {
+    return { ok: false, status: 0 };
+  }
+  const ac = new AbortController();
+  const t = setTimeout(() => ac.abort(), FETCH_TIMEOUT_MS);
+  try {
+    const r = await fetch(href, {
+      signal: ac.signal,
+      headers: {
+        Accept: 'application/vnd.github+json',
+        'User-Agent': 'm365-agent-cli-glitchtip-eligibility'
+      }
+    });
+    if (!r.ok) return { ok: false, status: r.status };
+    const data = (await r.json()) as T;
+    return { ok: true, data, status: r.status };
+  } catch {
+    return { ok: false, status: 0 };
+  } finally {
+    clearTimeout(t);
+  }
+}
+
+async function fetchNpmLatestVersion(): Promise<string | null> {
+  const url = `https://registry.npmjs.org/${NPM_PKG}/latest`;
+  const r = await fetchJson<{ version?: string }>(url);
+  if (!r.ok || !r.data?.version) return null;
+  return r.data.version.trim();
+}
+
+/** Resolve annotated or lightweight tag to commit SHA. */
+async function resolveTagCommitSha(owner: string, repo: string, version: string): Promise<string | null> {
+  const refUrl = `https://api.github.com/repos/${owner}/${repo}/git/ref/tags/v${encodeURIComponent(version)}`;
+  const ref = await fetchJson<{ object?: { sha?: string; type?: string } }>(refUrl);
+  if (!ref.ok || !ref.data?.object?.sha) return null;
+  const { sha, type } = ref.data.object;
+  if (type === 'commit') return sha;
+  if (type === 'tag') {
+    const tagUrl = `https://api.github.com/repos/${owner}/${repo}/git/tags/${sha}`;
+    const tag = await fetchJson<{ object?: { sha?: string; type?: string } }>(tagUrl);
+    if (!tag.ok || !tag.data?.object?.sha) return null;
+    return tag.data.object.sha;
+  }
+  return null;
+}
+
+function normalizeSha(s: string): string {
+  return s.trim().toLowerCase();
+}
+
+/**
+ * Returns whether GlitchTip should initialize. Uses cached npm + GitHub tag resolution (~1h).
+ */
+export async function checkGlitchTipEligibility(): Promise<GlitchTipEligibility> {
+  if (process.env.GLITCHTIP_SKIP_VERSION_CHECK === '1' || process.env.GLITCHTIP_SKIP_VERSION_CHECK === 'true') {
+    return { ok: true, reason: 'GLITCHTIP_SKIP_VERSION_CHECK' };
+  }
+
+  const currentVersion = await getPackageVersion();
+  const coords = await readGithubCoords();
+  if (!coords) {
+    return { ok: false, reason: 'package.json repository URL could not be parsed for GitHub' };
+  }
+
+  let cache = await loadCache();
+  const now = Date.now();
+  let npmLatest: string;
+  let tagCommitSha: string | null;
+
+  if (cache && now - cache.fetchedAt < CACHE_TTL_MS && cache.npmLatest) {
+    npmLatest = cache.npmLatest;
+    tagCommitSha = cache.tagCommitSha;
+  } else {
+    const nv = await fetchNpmLatestVersion();
+    if (!nv) {
+      return { ok: false, reason: 'could not fetch latest version from npm registry' };
+    }
+    npmLatest = nv;
+    tagCommitSha = await resolveTagCommitSha(coords.owner, coords.repo, npmLatest);
+    cache = { fetchedAt: now, npmLatest, tagCommitSha };
+    try {
+      await saveCache(cache);
+    } catch {
+      // cache is optional
+    }
+  }
+
+  if (currentVersion !== npmLatest) {
+    return {
+      ok: false,
+      reason: `not on latest npm release (running ${currentVersion}, latest is ${npmLatest})`
+    };
+  }
+
+  const localSha = normalizeSha(COMMIT_SHA);
+  if (localSha === 'unknown') {
+    if (
+      process.env.GLITCHTIP_ALLOW_UNVERIFIED_COMMIT === '1' ||
+      process.env.GLITCHTIP_ALLOW_UNVERIFIED_COMMIT === 'true'
+    ) {
+      return {
+        ok: true,
+        reason: 'COMMIT_SHA unknown; allowed by GLITCHTIP_ALLOW_UNVERIFIED_COMMIT (git match skipped)'
+      };
+    }
+    return {
+      ok: false,
+      reason:
+        'COMMIT_SHA is unknown — run `npm run embed-sha` from a git checkout before release, or set GLITCHTIP_ALLOW_UNVERIFIED_COMMIT=1'
+    };
+  }
+
+  if (!tagCommitSha) {
+    return {
+      ok: false,
+      reason: `could not resolve GitHub tag v${npmLatest} (create tag on the release commit)`
+    };
+  }
+
+  if (normalizeSha(tagCommitSha) !== localSha) {
+    return {
+      ok: false,
+      reason: `embedded commit does not match GitHub tag v${npmLatest} (local ${localSha.slice(0, 7)}… vs tag ${normalizeSha(tagCommitSha).slice(0, 7)}…)`
+    };
+  }
+
+  return { ok: true, reason: `npm ${npmLatest} and commit match tag v${npmLatest}` };
+}

package/src/lib/glitchtip.ts

@@ -0,0 +1,253 @@
+/**
+ * Optional error reporting to [GlitchTip](https://glitchtip.com/) (Sentry-compatible ingest).
+ * Set `GLITCHTIP_DSN` or `SENTRY_DSN` to enable. No reporting when unset.
+ *
+ * Events are scrubbed to avoid PII: no argv content, no user/request/breadcrumbs, paths and
+ * messages redacted (see stripSensitiveEventData).
+ */
+
+import type { ErrorEvent, EventHint, StackFrame } from '@sentry/core';
+import { captureException, flush, init, isInitialized } from '@sentry/node';
+import { checkGlitchTipEligibility } from './glitchtip-eligibility.js';
+import { getPackageVersionSync } from './package-info.js';
+
+/** Keys we never attach to reports (callers may pass `extra`; these are dropped). */
+const EXTRA_KEY_DENYLIST =
+  /^(body|bodyHtml|html|text|message|subject|snippet|preview|email|mail|address|token|password|secret|authorization|refresh|credential|content|attachment)/i;
+
+const EMAIL_RE = /\b[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[A-Za-z]{2,}\b/g;
+/** Looks like a JWT or opaque bearer token (redact). */
+const JWT_LIKE_RE = /\beyJ[A-Za-z0-9_-]{10,}\.[A-Za-z0-9_-]{10,}\.[A-Za-z0-9_-]{10,}\b/gi;
+
+function redactString(s: string): string {
+  return s
+    .replace(EMAIL_RE, '[email]')
+    .replace(JWT_LIKE_RE, '[token]')
+    .replace(/Bearer\s+[A-Za-z0-9._~-]+/gi, 'Bearer [token]')
+    .replace(/\\Users\\[^\\]+\\/gi, '\\Users\\<user>\\')
+    .replace(/\/Users\/[^/]+/g, '/Users/<user>')
+    .replace(/\/home\/[^/]+/g, '/home/<user>');
+}
+
+function deepRedactValue(value: unknown, depth = 0): unknown {
+  if (depth > 6) return '[truncated]';
+  if (typeof value === 'string') return redactString(value);
+  if (value === null || typeof value !== 'object') return value;
+  if (Array.isArray(value)) return value.slice(0, 50).map((v) => deepRedactValue(v, depth + 1));
+  const out: Record<string, unknown> = {};
+  for (const [k, v] of Object.entries(value)) {
+    if (EXTRA_KEY_DENYLIST.test(k)) continue;
+    out[k] = deepRedactValue(v, depth + 1);
+  }
+  return out;
+}
+
+function sanitizeExtraForReport(extra: Record<string, unknown>): Record<string, unknown> {
+  const cleaned: Record<string, unknown> = {};
+  for (const [k, v] of Object.entries(extra)) {
+    if (EXTRA_KEY_DENYLIST.test(k)) continue;
+    cleaned[k] = deepRedactValue(v);
+  }
+  return cleaned;
+}
+
+/** Remove PII from the outbound event; keeps stack structure for debugging. */
+function stripSensitiveEventData(event: ErrorEvent): void {
+  delete event.user;
+  delete event.request;
+  delete event.server_name;
+  event.breadcrumbs = [];
+
+  if (event.sdkProcessingMetadata) {
+    delete event.sdkProcessingMetadata;
+  }
+
+  if (event.message) {
+    event.message = redactString(event.message);
+  }
+  if (event.logentry?.message) {
+    event.logentry.message = redactString(event.logentry.message);
+  }
+
+  if (event.extra) {
+    const next: Record<string, unknown> = {};
+    for (const [k, v] of Object.entries(event.extra)) {
+      if (EXTRA_KEY_DENYLIST.test(k)) continue;
+      next[k] = deepRedactValue(v);
+    }
+    event.extra = next;
+  }
+
+  if (event.tags) {
+    const next: Record<string, string | number | boolean> = {};
+    for (const [k, v] of Object.entries(event.tags)) {
+      if (typeof v === 'string') next[k] = redactString(v);
+      else if (typeof v === 'number' || typeof v === 'boolean') next[k] = v;
+    }
+    event.tags = next;
+  }
+
+  const exValues = event.exception?.values;
+  if (exValues) {
+    for (const ex of exValues) {
+      if (ex.value) ex.value = redactString(ex.value);
+      scrubFrames(ex.stacktrace?.frames);
+    }
+  }
+
+  if (event.modules) {
+    const next: Record<string, string> = {};
+    for (const [k, v] of Object.entries(event.modules)) {
+      next[k] = typeof v === 'string' ? redactString(v) : String(v);
+    }
+    event.modules = next;
+  }
+
+  if (event.contexts) {
+    const { os, runtime, app } = event.contexts;
+    event.contexts = {};
+    if (os && typeof os === 'object') {
+      const o = os as Record<string, unknown>;
+      event.contexts.os = {
+        name: typeof o.name === 'string' ? o.name : undefined,
+        version: typeof o.version === 'string' ? o.version : undefined,
+        kernel_version: typeof o.kernel_version === 'string' ? o.kernel_version : undefined
+      };
+    }
+    if (runtime && typeof runtime === 'object') {
+      event.contexts.runtime = runtime;
+    }
+    if (app && typeof app === 'object') {
+      const a = app as Record<string, unknown>;
+      event.contexts.app = {
+        app_start_time: typeof a.app_start_time === 'string' ? a.app_start_time : undefined,
+        app_memory: typeof a.app_memory === 'number' ? a.app_memory : undefined
+      };
+    }
+  }
+
+  if (event.threads?.values) {
+    for (const thread of event.threads.values) {
+      delete thread.name;
+      scrubFrames(thread.stacktrace?.frames);
+    }
+  }
+}
+
+function scrubFrames(frames: StackFrame[] | undefined): void {
+  if (!frames) return;
+  for (const frame of frames) {
+    if (frame.filename) frame.filename = redactString(frame.filename);
+    if (frame.abs_path) frame.abs_path = redactString(frame.abs_path);
+    if (frame.context_line) frame.context_line = redactString(frame.context_line);
+    if (frame.pre_context) frame.pre_context = frame.pre_context.map(redactString);
+    if (frame.post_context) frame.post_context = frame.post_context.map(redactString);
+    delete frame.vars;
+  }
+}
+
+function getDsn(): string | undefined {
+  const raw = process.env.GLITCHTIP_DSN?.trim() || process.env.SENTRY_DSN?.trim();
+  if (!raw) return undefined;
+  const disabled = process.env.GLITCHTIP_ENABLED === '0' || process.env.GLITCHTIP_ENABLED === 'false';
+  if (disabled) return undefined;
+  return raw;
+}
+
+/** Errno codes that usually indicate environment/network, not application bugs. */
+const DEFAULT_IGNORE_ERRNO = new Set([
+  'ECONNREFUSED',
+  'ECONNRESET',
+  'ETIMEDOUT',
+  'ENOTFOUND',
+  'EAI_AGAIN',
+  'ENETUNREACH'
+]);
+
+function beforeSend(event: ErrorEvent, hint: EventHint): ErrorEvent | null {
+  const reportAll = process.env.GLITCHTIP_REPORT_ALL === '1';
+  if (!reportAll) {
+    const ex = hint.originalException;
+    if (ex && typeof ex === 'object' && 'code' in ex) {
+      const code = String((ex as NodeJS.ErrnoException).code);
+      if (code && DEFAULT_IGNORE_ERRNO.has(code)) {
+        return null;
+      }
+    }
+
+    if (ex instanceof Error) {
+      const msg = ex.message;
+      if (/invalid[_ ]?grant|refresh[_ ]?token.*invalid|AADSTS\d+/i.test(msg)) {
+        return null;
+      }
+    }
+  }
+
+  stripSensitiveEventData(event);
+  enrichSafeEvent(event);
+  return event;
+}
+
+/** Safe CLI context only: no argv text (may contain addresses, paths, mail snippets). */
+function enrichSafeEvent(event: ErrorEvent): void {
+  const argv = process.argv.slice(2);
+  const first = argv[0];
+  event.tags = {
+    ...(event.tags ?? {}),
+    'cli.argc': String(argv.length)
+  };
+  if (first && /^[a-z][a-z0-9-]*$/i.test(first) && first.length <= 48) {
+    event.tags['cli.command'] = first;
+  }
+}
+
+let didInit = false;
+
+/** Call once after `loadGlobalEnv()` so `.env` can define `GLITCHTIP_DSN`. */
+export async function initGlitchTip(): Promise<void> {
+  if (didInit) return;
+  didInit = true;
+
+  const dsn = getDsn();
+  if (!dsn) return;
+
+  const eligibility = await checkGlitchTipEligibility();
+  if (!eligibility.ok) {
+    if (process.env.GLITCHTIP_DEBUG_ELIGIBILITY === '1' || process.env.GLITCHTIP_DEBUG_ELIGIBILITY === 'true') {
+      console.error(`[GlitchTip] Disabled: ${eligibility.reason ?? 'not eligible'}`);
+    }
+    return;
+  }
+
+  const releaseFromEnv = process.env.GLITCHTIP_RELEASE?.trim();
+  const release =
+    releaseFromEnv && releaseFromEnv.length > 0 ? releaseFromEnv : `m365-agent-cli@${getPackageVersionSync()}`;
+
+  init({
+    dsn,
+    sendDefaultPii: false,
+    environment: process.env.GLITCHTIP_ENVIRONMENT || process.env.NODE_ENV || 'production',
+    release,
+    tracesSampleRate: 0,
+    profilesSampleRate: 0,
+    maxBreadcrumbs: 0,
+    beforeBreadcrumb: () => null,
+    beforeSend: beforeSend as (event: ErrorEvent, hint: EventHint) => ErrorEvent | null
+  });
+}
+
+/** Wait for the transport to finish (call before `process.exit` after a capture). */
+export async function flushGlitchTip(timeoutMs = 2000): Promise<boolean> {
+  if (!isInitialized()) return true;
+  return flush(timeoutMs);
+}
+
+/** Report an exception (e.g. Commander parse failure). No-op if GlitchTip is not configured. */
+export function captureCliException(error: unknown, extra?: Record<string, unknown>): void {
+  if (!isInitialized()) return;
+  if (extra && Object.keys(extra).length > 0) {
+    captureException(error, { extra: sanitizeExtraForReport(extra) });
+  } else {
+    captureException(error);
+  }
+}

package/src/lib/global-env.ts

@@ -0,0 +1,3 @@
+import { loadGlobalEnv } from './utils.js';
+
+loadGlobalEnv();