@sentry/warden 0.0.0

package/src/cli/commands/setup-app/browser.ts

@@ -0,0 +1,38 @@
+/**
+ * Cross-platform browser opener.
+ */
+
+import { exec } from 'node:child_process';
+import { platform } from 'node:os';
+
+/**
+ * Open a URL in the default browser.
+ * Returns a promise that resolves when the browser open command has been executed.
+ */
+export function openBrowser(url: string): Promise<void> {
+  return new Promise((resolve, reject) => {
+    const os = platform();
+    let command: string;
+
+    switch (os) {
+      case 'darwin':
+        command = `open "${url}"`;
+        break;
+      case 'win32':
+        command = `start "" "${url}"`;
+        break;
+      default:
+        // Linux and others
+        command = `xdg-open "${url}"`;
+        break;
+    }
+
+    exec(command, (error) => {
+      if (error) {
+        reject(error);
+      } else {
+        resolve();
+      }
+    });
+  });
+}

package/src/cli/commands/setup-app/credentials.ts

@@ -0,0 +1,45 @@
+/**
+ * Exchange temporary code for GitHub App credentials via GitHub API.
+ */
+
+export interface AppCredentials {
+  id: number;
+  name: string;
+  pem: string;
+  htmlUrl: string;
+}
+
+/**
+ * Exchange a temporary code for GitHub App credentials.
+ * This uses the GitHub API to convert the code into full app credentials.
+ */
+export async function exchangeCodeForCredentials(code: string): Promise<AppCredentials> {
+  const url = `https://api.github.com/app-manifests/${code}/conversions`;
+
+  const response = await fetch(url, {
+    method: 'POST',
+    headers: {
+      Accept: 'application/vnd.github+json',
+      'X-GitHub-Api-Version': '2022-11-28',
+    },
+  });
+
+  if (!response.ok) {
+    const errorText = await response.text();
+    throw new Error(`Failed to exchange code for credentials: ${response.status} ${response.statusText}\n${errorText}`);
+  }
+
+  const data = (await response.json()) as {
+    id: number;
+    name: string;
+    pem: string;
+    html_url: string;
+  };
+
+  return {
+    id: data.id,
+    name: data.name,
+    pem: data.pem,
+    htmlUrl: data.html_url,
+  };
+}

package/src/cli/commands/setup-app/manifest.ts

@@ -0,0 +1,48 @@
+/**
+ * GitHub App manifest builder for the setup-app flow.
+ */
+
+export interface ManifestOptions {
+  name?: string;
+  port: number;
+}
+
+export interface GitHubAppManifest {
+  name: string;
+  url: string;
+  hook_attributes: {
+    url: string;
+    active: boolean;
+  };
+  redirect_url: string;
+  public: boolean;
+  default_permissions: Record<string, string>;
+  default_events: string[];
+}
+
+/**
+ * Build a GitHub App manifest for Warden.
+ */
+export function buildManifest(options: ManifestOptions): GitHubAppManifest {
+  const name = options.name ?? 'Warden';
+
+  return {
+    name,
+    url: 'https://github.com/getsentry/warden',
+    hook_attributes: {
+      // URL is required by GitHub even when webhooks are disabled
+      url: 'https://example.com/webhook',
+      active: false,
+    },
+    redirect_url: `http://localhost:${options.port}/callback`,
+    public: false,
+    default_permissions: {
+      contents: 'read',
+      pull_requests: 'write',
+      issues: 'write',
+      checks: 'write',
+      metadata: 'read',
+    },
+    default_events: ['pull_request'],
+  };
+}

package/src/cli/commands/setup-app/server.ts

@@ -0,0 +1,172 @@
+/**
+ * Local HTTP server for GitHub App manifest flow.
+ * Serves a form that POSTs the manifest to GitHub, then receives the callback.
+ */
+
+import { createServer, type Server, type IncomingMessage, type ServerResponse } from 'node:http';
+import { URL } from 'node:url';
+import type { GitHubAppManifest } from './manifest.js';
+
+export interface CallbackResult {
+  code: string;
+}
+
+export interface ServerOptions {
+  port: number;
+  expectedState: string;
+  timeoutMs: number;
+  manifest: GitHubAppManifest;
+  org?: string;
+}
+
+/**
+ * Build the HTML page that auto-submits the manifest form to GitHub.
+ */
+function buildStartPage(manifest: GitHubAppManifest, state: string, org?: string): string {
+  const githubUrl = org
+    ? `https://github.com/organizations/${org}/settings/apps/new?state=${state}`
+    : `https://github.com/settings/apps/new?state=${state}`;
+
+  const manifestJson = JSON.stringify(manifest);
+
+  return `<!DOCTYPE html>
+<html>
+<head>
+  <title>Creating GitHub App...</title>
+  <style>
+    body { font-family: -apple-system, BlinkMacSystemFont, sans-serif; text-align: center; padding: 50px; }
+    .spinner { border: 4px solid #f3f3f3; border-top: 4px solid #3498db; border-radius: 50%; width: 40px; height: 40px; animation: spin 1s linear infinite; margin: 20px auto; }
+    @keyframes spin { 0% { transform: rotate(0deg); } 100% { transform: rotate(360deg); } }
+  </style>
+</head>
+<body>
+  <h1>Redirecting to GitHub...</h1>
+  <div class="spinner"></div>
+  <p>If you are not redirected automatically, click the button below.</p>
+  <form id="manifest-form" action="${githubUrl}" method="post">
+    <input type="hidden" name="manifest" value='${manifestJson.replace(/'/g, '&#39;')}'>
+    <button type="submit" style="padding: 10px 20px; font-size: 16px; cursor: pointer;">Continue to GitHub</button>
+  </form>
+  <script>
+    // Auto-submit the form after a brief delay
+    setTimeout(function() {
+      document.getElementById('manifest-form').submit();
+    }, 500);
+  </script>
+</body>
+</html>`;
+}
+
+/**
+ * Create and start a local HTTP server for the manifest flow.
+ * - GET / or /start: Serves the form that POSTs to GitHub
+ * - GET /callback: Receives the callback from GitHub with the code
+ */
+export function startCallbackServer(options: ServerOptions): {
+  server: Server;
+  waitForCallback: Promise<CallbackResult>;
+  close: () => void;
+  startUrl: string;
+} {
+  let resolveCallback: (result: CallbackResult) => void;
+  let rejectCallback: (error: Error) => void;
+
+  const waitForCallback = new Promise<CallbackResult>((resolve, reject) => {
+    resolveCallback = resolve;
+    rejectCallback = reject;
+  });
+
+  const server = createServer((req: IncomingMessage, res: ServerResponse) => {
+    const url = new URL(req.url || '/', `http://localhost:${options.port}`);
+
+    // Serve the start page that auto-submits to GitHub
+    if (req.method === 'GET' && (url.pathname === '/' || url.pathname === '/start')) {
+      res.writeHead(200, { 'Content-Type': 'text/html' });
+      res.end(buildStartPage(options.manifest, options.expectedState, options.org));
+      return;
+    }
+
+    // Handle callback from GitHub
+    if (req.method === 'GET' && url.pathname === '/callback') {
+      const code = url.searchParams.get('code');
+      const state = url.searchParams.get('state');
+
+      // Validate state parameter (CSRF protection)
+      if (state !== options.expectedState) {
+        res.writeHead(400, { 'Content-Type': 'text/html' });
+        res.end(`
+          <!DOCTYPE html>
+          <html>
+          <head><title>Error</title></head>
+          <body>
+            <h1>Error: Invalid state parameter</h1>
+            <p>This may be a CSRF attack. Please try again.</p>
+          </body>
+          </html>
+        `);
+        rejectCallback(new Error('Invalid state parameter - possible CSRF attack'));
+        return;
+      }
+
+      if (!code) {
+        res.writeHead(400, { 'Content-Type': 'text/html' });
+        res.end(`
+          <!DOCTYPE html>
+          <html>
+          <head><title>Error</title></head>
+          <body>
+            <h1>Error: Missing code parameter</h1>
+            <p>GitHub did not provide the expected authorization code.</p>
+          </body>
+          </html>
+        `);
+        rejectCallback(new Error('Missing code parameter in callback'));
+        return;
+      }
+
+      // Success - send response and resolve promise
+      res.writeHead(200, { 'Content-Type': 'text/html' });
+      res.end(`
+        <!DOCTYPE html>
+        <html>
+        <head>
+          <title>Success</title>
+          <style>
+            body { font-family: -apple-system, BlinkMacSystemFont, sans-serif; text-align: center; padding: 50px; }
+            h1 { color: #28a745; }
+          </style>
+        </head>
+        <body>
+          <h1>GitHub App Created!</h1>
+          <p>You can close this window and return to the terminal.</p>
+        </body>
+        </html>
+      `);
+
+      resolveCallback({ code });
+      return;
+    }
+
+    // 404 for anything else
+    res.writeHead(404);
+    res.end('Not found');
+  });
+
+  // Bind only to localhost for security
+  server.listen(options.port, '127.0.0.1');
+
+  // Set up timeout
+  const timeoutId = setTimeout(() => {
+    rejectCallback(new Error(`Timeout: No callback received within ${options.timeoutMs / 1000} seconds`));
+    server.close();
+  }, options.timeoutMs);
+
+  const close = () => {
+    clearTimeout(timeoutId);
+    server.close();
+  };
+
+  const startUrl = `http://localhost:${options.port}/start`;
+
+  return { server, waitForCallback, close, startUrl };
+}

package/src/cli/commands/setup-app.ts

@@ -0,0 +1,156 @@
+/**
+ * Setup GitHub App command.
+ * Creates a GitHub App via the manifest flow for Warden to post as a custom bot.
+ */
+
+import { randomBytes } from 'node:crypto';
+import chalk from 'chalk';
+import type { SetupAppOptions } from '../args.js';
+import type { Reporter } from '../output/reporter.js';
+import { getGitHubRepoUrl } from '../git.js';
+import { buildManifest } from './setup-app/manifest.js';
+import { startCallbackServer } from './setup-app/server.js';
+import { openBrowser } from './setup-app/browser.js';
+import { exchangeCodeForCredentials } from './setup-app/credentials.js';
+
+/**
+ * Run the setup-app command.
+ */
+export async function runSetupApp(options: SetupAppOptions, reporter: Reporter): Promise<number> {
+  const { port, timeout, org, name, open } = options;
+
+  reporter.bold('SETUP GITHUB APP');
+  reporter.blank();
+
+  // Generate state token for CSRF protection
+  const state = randomBytes(16).toString('hex');
+
+  // Build manifest
+  const manifest = buildManifest({ name, port });
+
+  // Show what permissions will be requested
+  reporter.text('This will create a GitHub App with the following permissions:');
+  reporter.text(`  ${chalk.dim('•')} contents: read        ${chalk.dim('- Read repository files')}`);
+  reporter.text(`  ${chalk.dim('•')} pull_requests: write  ${chalk.dim('- Post review comments')}`);
+  reporter.text(`  ${chalk.dim('•')} issues: write         ${chalk.dim('- Create/update issues')}`);
+  reporter.text(`  ${chalk.dim('•')} checks: write         ${chalk.dim('- Create check runs')}`);
+  reporter.text(`  ${chalk.dim('•')} metadata: read        ${chalk.dim('- Read repository metadata')}`);
+  reporter.blank();
+
+  // Start local server (serves the form and handles callback)
+  reporter.step(`Starting local server on http://localhost:${port}...`);
+
+  const serverHandle = startCallbackServer({
+    port,
+    expectedState: state,
+    timeoutMs: timeout * 1000,
+    manifest,
+    org,
+  });
+
+  // Handle server errors (e.g., port already in use)
+  serverHandle.server.on('error', (error: NodeJS.ErrnoException) => {
+    if (error.code === 'EADDRINUSE') {
+      reporter.error(`Port ${port} is already in use. Try a different port with --port <number>`);
+    } else {
+      reporter.error(`Server error: ${error.message}`);
+    }
+    process.exit(1);
+  });
+
+  try {
+    // Open browser to our local server (which will POST to GitHub)
+    if (open) {
+      reporter.step('Opening browser...');
+      try {
+        await openBrowser(serverHandle.startUrl);
+      } catch {
+        reporter.warning('Could not open browser automatically.');
+        reporter.blank();
+        reporter.text('Open this URL in your browser:');
+        reporter.text(chalk.cyan(serverHandle.startUrl));
+      }
+    } else {
+      reporter.blank();
+      reporter.text('Open this URL in your browser:');
+      reporter.text(chalk.cyan(serverHandle.startUrl));
+    }
+
+    reporter.blank();
+    reporter.text(`On the GitHub page, click ${chalk.cyan('"Create GitHub App"')} to continue.`);
+    reporter.blank();
+    reporter.text(chalk.dim('Waiting for GitHub callback... (Ctrl+C to cancel)'));
+
+    // Wait for callback
+    const { code } = await serverHandle.waitForCallback;
+
+    // Exchange code for credentials
+    reporter.blank();
+    reporter.step('Exchanging code for credentials...');
+    const credentials = await exchangeCodeForCredentials(code);
+
+    // Success!
+    reporter.blank();
+    reporter.success('GitHub App created!');
+    reporter.blank();
+    reporter.text(`  App ID:    ${chalk.cyan(credentials.id)}`);
+    reporter.text(`  App Name:  ${chalk.cyan(credentials.name)}`);
+    reporter.text(`  App URL:   ${chalk.cyan(credentials.htmlUrl)}`);
+    reporter.blank();
+
+    // Next steps - in correct order!
+    const githubRepoUrl = getGitHubRepoUrl(process.cwd());
+    reporter.bold('Next steps:');
+    reporter.blank();
+
+    // Step 1: Install the app (must happen first!)
+    reporter.text(`  ${chalk.cyan('1.')} Install the app on your repository:`);
+    reporter.text(`     ${chalk.cyan(credentials.htmlUrl + '/installations/new')}`);
+    reporter.blank();
+
+    // Step 2: Add secrets
+    reporter.text(`  ${chalk.cyan('2.')} Add these secrets to your repository:`);
+    if (githubRepoUrl) {
+      reporter.text(`     ${chalk.cyan(githubRepoUrl + '/settings/secrets/actions')}`);
+    }
+    reporter.blank();
+    reporter.text(`     ${chalk.white('WARDEN_APP_ID')}          ${credentials.id}`);
+    reporter.text(`     ${chalk.white('WARDEN_PRIVATE_KEY')}     ${chalk.dim('(copy the key below)')}`);
+    reporter.blank();
+
+    // Private key with clear instructions
+    reporter.text(`  ${chalk.cyan('Private Key')} ${chalk.dim('(copy entire block including BEGIN/END lines):')}`);
+    reporter.blank();
+    // Indent the private key for readability
+    const pemLines = credentials.pem.trim().split('\n');
+    for (const line of pemLines) {
+      reporter.text(`     ${chalk.dim(line)}`);
+    }
+    reporter.blank();
+
+    return 0;
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    reporter.error(message);
+    reporter.blank();
+
+    // Provide recovery guidance if the app might have been created
+    const githubRepoUrl = getGitHubRepoUrl(process.cwd());
+    reporter.text(chalk.dim('If the GitHub App was created before this error:'));
+    reporter.text(chalk.dim('  1. Go to https://github.com/settings/apps' + (org ? ` (or your org's settings)` : '')));
+    reporter.text(chalk.dim('  2. Find your app and click "Edit"'));
+    reporter.text(chalk.dim('  3. Note the App ID from the "About" section'));
+    reporter.text(chalk.dim('  4. Scroll to "Private keys" and click "Generate a private key"'));
+    reporter.text(chalk.dim('  5. Install the app: click "Install App" in the sidebar'));
+    reporter.text(chalk.dim('  6. Add secrets to your repository:'));
+    if (githubRepoUrl) {
+      reporter.text(chalk.dim(`     ${githubRepoUrl}/settings/secrets/actions`));
+    }
+    reporter.text(chalk.dim('     - WARDEN_APP_ID: your App ID'));
+    reporter.text(chalk.dim('     - WARDEN_PRIVATE_KEY: contents of the downloaded .pem file'));
+
+    return 1;
+  } finally {
+    serverHandle.close();
+  }
+}

package/src/cli/commands/sync.ts

@@ -0,0 +1,114 @@
+import chalk from 'chalk';
+import {
+  fetchRemote,
+  listCachedRemotes,
+  parseRemoteRef,
+} from '../../skills/remote.js';
+import type { Reporter } from '../output/reporter.js';
+import type { CLIOptions } from '../args.js';
+
+/**
+ * Run the sync command.
+ * Updates cached remote skills to their latest versions.
+ * Pinned skills (with @sha) are skipped as they're immutable.
+ */
+export async function runSync(options: CLIOptions, reporter: Reporter): Promise<number> {
+  const cachedRemotes = listCachedRemotes();
+
+  if (cachedRemotes.length === 0) {
+    reporter.warning('No remote skills cached.');
+    reporter.tip('Add remote skills with: warden add --remote owner/repo --skill name');
+    return 0;
+  }
+
+  // If a specific remote is provided, only sync that one
+  const targetRepo = options.remote;
+  const remotesToSync = targetRepo
+    ? cachedRemotes.filter(({ ref }) => ref === targetRepo || ref.startsWith(`${targetRepo}@`))
+    : cachedRemotes;
+
+  if (targetRepo && remotesToSync.length === 0) {
+    reporter.error(`Remote not found in cache: ${targetRepo}`);
+    reporter.blank();
+    reporter.text('Cached remotes:');
+    for (const { ref } of cachedRemotes) {
+      reporter.text(`  - ${ref}`);
+    }
+    return 1;
+  }
+
+  // Separate pinned and unpinned remotes
+  const unpinnedRemotes = remotesToSync.filter(({ ref }) => {
+    const parsed = parseRemoteRef(ref);
+    return !parsed.sha;
+  });
+
+  const pinnedRemotes = remotesToSync.filter(({ ref }) => {
+    const parsed = parseRemoteRef(ref);
+    return !!parsed.sha;
+  });
+
+  if (unpinnedRemotes.length === 0) {
+    if (pinnedRemotes.length > 0) {
+      reporter.warning('All cached remotes are pinned to specific versions.');
+      reporter.text('Pinned remotes do not need syncing as they are immutable.');
+      for (const { ref } of pinnedRemotes) {
+        reporter.text(`  - ${ref} ${chalk.dim('(pinned)')}`);
+      }
+    } else {
+      reporter.warning('No remotes to sync.');
+    }
+    return 0;
+  }
+
+  reporter.bold('SYNC REMOTE SKILLS');
+  reporter.blank();
+
+  let updated = 0;
+  let errors = 0;
+
+  for (const { ref, entry } of unpinnedRemotes) {
+    reporter.step(`Syncing ${ref}...`);
+
+    const previousSha = entry.sha;
+
+    try {
+      const newSha = await fetchRemote(ref, { force: true });
+
+      if (newSha !== previousSha) {
+        reporter.success(`${ref}: updated ${chalk.dim(previousSha.slice(0, 7))} -> ${chalk.dim(newSha.slice(0, 7))}`);
+        updated++;
+      } else {
+        reporter.text(`${ref}: ${chalk.dim('already up to date')}`);
+      }
+    } catch (err) {
+      const message = err instanceof Error ? err.message : String(err);
+      reporter.error(`${ref}: ${message}`);
+      errors++;
+    }
+  }
+
+  // Show pinned remotes that were skipped
+  if (pinnedRemotes.length > 0 && !targetRepo) {
+    reporter.blank();
+    reporter.text(chalk.dim('Skipped pinned remotes:'));
+    for (const { ref } of pinnedRemotes) {
+      reporter.text(chalk.dim(`  - ${ref}`));
+    }
+  }
+
+  // Summary
+  reporter.blank();
+  if (errors > 0) {
+    reporter.warning(`Synced with ${errors} error${errors === 1 ? '' : 's'}.`);
+    return 1;
+  }
+
+  if (updated > 0) {
+    reporter.success(`Updated ${updated} remote${updated === 1 ? '' : 's'}.`);
+  } else {
+    reporter.success('All remotes up to date.');
+  }
+
+  return 0;
+}