@rootly/wizard 0.1.0

package/src/actions/integrations.js

@@ -0,0 +1,75 @@
+import { spawn } from 'node:child_process';
+
+const DEFAULT_APP_BASE_URL = process.env.ROOTLY_APP_URL?.trim() || 'https://rootly.com';
+
+// Vendors that are alert sources deep-link to the "new alert source" form with
+// the source type preselected. The values are the Rails STI class names
+// (Alerts::<X>Source) the form expects in alerts_source[sourceable_type].
+const ALERT_SOURCE_TYPES = {
+  Datadog: 'Alerts::DatadogSource',
+  Grafana: 'Alerts::GrafanaSource',
+  Sentry: 'Alerts::SentrySource'
+};
+
+export function webHandoffUrl(kind, appBaseUrl = DEFAULT_APP_BASE_URL) {
+  const sourceableType = ALERT_SOURCE_TYPES[kind];
+  if (sourceableType) {
+    // e.g. /account/alert-sources/new?alerts_source%5Bsourceable_type%5D=Alerts%3A%3ADatadogSource
+    return `${appBaseUrl}/account/alert-sources/new?alerts_source%5Bsourceable_type%5D=${encodeURIComponent(sourceableType)}`;
+  }
+
+  switch (kind) {
+    case 'Slack':
+      return `${appBaseUrl}/account/integrations/slack_accounts/landing`;
+    case 'Phone':
+      // User profile, where phone numbers and notification rules are managed.
+      return `${appBaseUrl}/account/profile`;
+    case 'PagerDuty':
+      // Not an alert source — PagerDuty connects as an escalation integration.
+      return `${appBaseUrl}/account/integrations/pagerduty_accounts/new`;
+    case 'Opsgenie':
+      // Not an alert source — Opsgenie connects as an escalation integration.
+      return `${appBaseUrl}/account/integrations/opsgenie_accounts/new`;
+    default:
+      // The unified alert sources tab — where any alert source is added.
+      return `${appBaseUrl}/account/alerts?tab=alert-sources#add-alert-sources-section`;
+  }
+}
+
+export function openUrl(url) {
+  const platform = process.platform;
+
+  return new Promise((resolve) => {
+    let child;
+
+    if (platform === 'darwin') {
+      child = spawn('open', [url], { stdio: 'ignore' });
+    } else if (platform === 'win32') {
+      child = spawn('cmd', ['/c', 'start', '', url], { stdio: 'ignore', windowsHide: true });
+    } else {
+      child = spawn('xdg-open', [url], { stdio: 'ignore' });
+    }
+
+    child.on('error', () => resolve(false));
+    child.on('spawn', () => {
+      child.unref();
+      resolve(true);
+    });
+  });
+}
+
+export async function startWebHandoffAction({ kind, open = false, appBaseUrl } = {}) {
+  const url = webHandoffUrl(kind, appBaseUrl || DEFAULT_APP_BASE_URL);
+  const opened = open ? await openUrl(url) : false;
+
+  return {
+    ok: true,
+    summary: `${kind} setup still uses the Rootly web flow.`,
+    data: {
+      kind,
+      url,
+      opened,
+      detectable: kind === 'Slack'
+    }
+  };
+}

package/src/actions/mcp.js

@@ -0,0 +1,52 @@
+import { buildHostedMcpPreview, getMcpConfigPath, verifyHostedMcpConfig, writeHostedMcpConfig } from '../mcp.js';
+import { getStoredToken } from '../auth.js';
+
+export async function previewMcpSetupAction({ clients = [], auth = 'Use stored token' } = {}) {
+  return {
+    ok: true,
+    summary: 'Built MCP preview.',
+    data: {
+      clients,
+      auth,
+      preview: clients.map((client) => buildHostedMcpPreview(client, auth)),
+      paths: clients.map((client) => ({
+        client,
+        path: getMcpConfigPath(client)
+      }))
+    }
+  };
+}
+
+export async function applyMcpSetupAction({ clients = [], auth = 'Use stored token' } = {}) {
+  const token = auth === 'Use ROOTLY_TOKEN'
+    ? process.env.ROOTLY_TOKEN?.trim()
+    : await getStoredToken();
+
+  if (!token) {
+    return {
+      ok: false,
+      code: 'NO_AUTH',
+      summary: auth === 'Use ROOTLY_TOKEN'
+        ? 'ROOTLY_TOKEN was not found in the environment.'
+        : 'No stored Rootly token was found.',
+      data: null
+    };
+  }
+
+  const results = [];
+  for (const client of clients) {
+    const { targetPath, backupPath } = await writeHostedMcpConfig(client, token);
+    await verifyHostedMcpConfig(client);
+    results.push({ client, targetPath, backupPath });
+  }
+
+  return {
+    ok: true,
+    summary: 'Configured MCP for selected clients.',
+    data: {
+      clients,
+      auth,
+      results
+    }
+  };
+}

package/src/actions/oneshot.js

@@ -0,0 +1,243 @@
+import { loadApiClient, extractUserId, isServiceAccount } from '../runtime.js';
+import { getAuthSummary } from '../auth.js';
+import {
+  addTeamMembersByIdsAction,
+  createAlertSourceAction,
+  createEscalationPolicyAction,
+  createScheduleAction,
+  createTeamAction
+} from './setup.js';
+import { createTestAlertAction, createTestIncidentAction } from './testing.js';
+
+function stepError(error) {
+  return error?.message?.replace(/^Rootly API request failed for [^:]+:\s*/, '') || 'unknown error';
+}
+
+// OAuth sessions can't write teams/schedules (they 403/404). Classify those so
+// the summary can explain the sign-in lacks the capability, rather than
+// surfacing a generic failure.
+function isPermissionFailure(error) {
+  const message = error?.message || '';
+  return /\b40[134]\b/.test(message) || /Not found or unauthorized/i.test(message);
+}
+
+// Take a brand-new account from nothing to a visible alert + incident in one
+// call. Auto-detects the sign-in's capabilities: an API key runs the whole
+// chain, while a browser (OAuth) session does as much as it is allowed and the
+// result explains what it could not write.
+//
+// `onStep` (optional) is awaited before and after each step with
+// { step, status: 'running' | 'ok' | 'reused' | 'blocked' | 'failed' }, so a UI
+// can show live progress (and pace it).
+export async function runOneShotSetupAction({
+  teamName = 'Incident Response',
+  handoffTime = '09:00',
+  memberIds = []
+} = {}, onStep) {
+  const api = await loadApiClient();
+  const authSummary = await getAuthSummary();
+  const authMode = authSummary?.mode || 'stored-token';
+  const isOAuth = authMode === 'oauth';
+
+  const steps = [];
+  const blocked = [];
+  const emit = (step, status, extra = {}) => onStep?.({ step, status, ...extra });
+  const record = (step, status, { id = null, error = null } = {}) => {
+    steps.push({ step, status, id, error });
+    if (status === 'blocked') blocked.push(step);
+  };
+
+  // Run a guarded mutating step; permission failures become 'blocked' (the
+  // chain continues) and everything else becomes 'failed'. Progress is emitted
+  // around each attempt.
+  const run = async (step, fn) => {
+    await emit(step, 'running');
+    try {
+      const res = await fn();
+      record(step, 'ok', { id: res?.data?.id ?? null });
+      await emit(step, 'ok');
+      return res;
+    } catch (error) {
+      const status = isPermissionFailure(error) ? 'blocked' : 'failed';
+      const message = stepError(error);
+      record(step, status, { error: message });
+      await emit(step, status, { error: message });
+      return null;
+    }
+  };
+
+  const data = {
+    authMode,
+    team: null,
+    members: [],
+    rotation: [],
+    schedule: null,
+    escalationPolicy: null,
+    alertSource: null,
+    alert: null,
+    incident: null,
+    steps
+  };
+
+  const currentUser = await api.getCurrentUser();
+  const currentUserId = extractUserId(currentUser);
+  const serviceAccount = isServiceAccount(currentUser);
+
+  // The humans to put on the team + rotation. When none are chosen, fall back
+  // to the current identity (even an API-key bot) so the rotation is never
+  // empty and the demo shows someone on call.
+  const chosenIds = (memberIds || []).map((id) => String(id)).filter(Boolean);
+  const rotationIds = chosenIds.length ? chosenIds : (currentUserId ? [String(currentUserId)] : []);
+  data.members = chosenIds;
+  data.rotation = rotationIds;
+
+  // 1. Team — reuse the signed-in user's existing team so a re-run doesn't pile
+  // up duplicates. A user-less API key has none, so it creates one.
+  let teamId = null;
+  const existingTeamIds = currentUser?.data?.relationships?.teams?.data?.map((team) => team.id) || [];
+  if (existingTeamIds.length) {
+    await emit('team', 'running');
+    teamId = existingTeamIds[0];
+    let reusedName = null;
+    try {
+      const teamPayload = await api.getTeam(teamId);
+      reusedName = teamPayload?.data?.attributes?.name || null;
+    } catch {
+      // best-effort; the name is only for display.
+    }
+    record('team', 'reused', { id: teamId });
+    data.team = { id: teamId, name: reusedName, reused: true };
+    await emit('team', 'reused');
+  } else {
+    const teamResult = await run('team', () =>
+      createTeamAction({ name: teamName, enableAlertsAndBroadcast: true })
+    );
+    if (teamResult) {
+      teamId = teamResult.data.id;
+      data.team = { id: teamId, name: teamResult.data.name, reused: false };
+    }
+  }
+
+  const teamLabel = data.team?.name || teamName;
+
+  // 2-4. Team-dependent scaffolding — only if a team is in place.
+  if (teamId) {
+    if (chosenIds.length) {
+      await run('members', () => addTeamMembersByIdsAction({ teamId, userIds: chosenIds }));
+    }
+
+    // Reuse existing resources by name so a re-run doesn't fail on "already
+    // exists" — which previously broke the paging chain (no escalation policy →
+    // the test alert reached no one).
+    const schedule = await run('schedule', () =>
+      createScheduleAction({ teamId, name: `${teamLabel} On-Call`, handoffTime, memberIds: rotationIds, reuseByName: true })
+    );
+    if (schedule) {
+      data.schedule = {
+        id: schedule.data.scheduleId,
+        name: `${teamLabel} On-Call`,
+        handoffTime,
+        rotationCreated: schedule.data.rotationCreated
+      };
+    }
+
+    const escalation = await run('escalation-policy', () =>
+      createEscalationPolicyAction({
+        teamId,
+        name: `${teamLabel} Escalation`,
+        repeatCount: 1,
+        createDefaultPath: Boolean(data.schedule),
+        // Add a level paging the on-call schedule so a triggered alert reaches a person.
+        scheduleId: data.schedule?.id || null,
+        reuseByName: true
+      })
+    );
+    if (escalation) data.escalationPolicy = { id: escalation.data.id, name: `${teamLabel} Escalation` };
+
+    const source = await run('alert-source', () =>
+      createAlertSourceAction({ teamId, name: `${teamLabel} Webhook`, reuseByName: true })
+    );
+    if (source) {
+      data.alertSource = {
+        id: source.data.id,
+        name: `${teamLabel} Webhook`,
+        webhookEndpoint: source.data.webhookEndpoint
+      };
+    }
+  }
+
+  // Status pages are no longer part of Quick start — they're offered as a
+  // guided flow after the run completes (see the incident-ready screen).
+
+  // 5. Test alert — the "see an alert" payoff, and the thing that actually
+  // pages you. When we have an escalation policy, trigger the alert against it
+  // (urgency high) so it escalates to the on-call person and rings their phone.
+  const groupIds = teamId ? [teamId] : [];
+  const alertSummary = 'Rootly setup test alert';
+
+  let highUrgencyId = null;
+  try {
+    const urgencies = await api.listAlertUrgencies();
+    const list = urgencies?.data || [];
+    highUrgencyId = (list.find((u) => /high/i.test(u?.attributes?.name || '')) || list[0])?.id || null;
+  } catch {
+    // best-effort; urgency is optional.
+  }
+
+  const policyId = data.escalationPolicy?.id || null;
+  const alert = await run('test-alert', () =>
+    createTestAlertAction({
+      summary: alertSummary,
+      description: 'Fired by the Rootly setup wizard to page on-call.',
+      groupIds,
+      ...(policyId
+        ? { notificationTargetType: 'EscalationPolicy', notificationTargetId: policyId, urgencyId: highUrgencyId }
+        : {})
+    })
+  );
+  if (alert) data.alert = { id: alert.data.id, summary: alertSummary, paged: Boolean(alert.data.paged) };
+
+  // 7. Test incident — the "see an incident" payoff. Attach a severity when the
+  // workspace exposes one (some workspaces require it).
+  let severityId = null;
+  try {
+    const severities = await api.listSeverities();
+    severityId = severities?.data?.[0]?.id || null;
+  } catch {
+    // best-effort; the incident action tolerates a null severity.
+  }
+  const incidentTitle = 'Rootly setup test incident';
+  const incident = await run('test-incident', () =>
+    createTestIncidentAction({
+      title: incidentTitle,
+      summary: 'Created by the Rootly setup wizard to show the incident flow.',
+      groupIds,
+      severityId
+    })
+  );
+  if (incident) {
+    data.incident = {
+      id: incident.data.id,
+      title: incidentTitle,
+      slackChannelName: incident.data.slackChannelName,
+      slackChannelUrl: incident.data.slackChannelUrl
+    };
+  }
+
+  const ok = Boolean(data.alert || data.incident);
+  const note = blocked.length
+    ? (isOAuth
+        ? `This browser sign-in can't write ${blocked.join(', ')} yet. Sign in with an API token to complete those, or have Rootly grant the OAuth app workspace write scopes.`
+        : `Could not complete: ${blocked.join(', ')}.`)
+    : null;
+
+  return {
+    ok,
+    summary: ok
+      ? `${data.incident ? 'Created a test incident' : 'Fired a test alert'}${
+          teamId ? ` for ${teamLabel}` : ''
+        }.`
+      : 'Could not create an alert or incident with this sign-in.',
+    data: { ...data, blocked, note }
+  };
+}

package/src/actions/phone.js

@@ -0,0 +1,122 @@
+import { loadApiClient, extractUserId } from '../runtime.js';
+
+// Returns the signed-in user's existing phone number (if any) for display.
+export async function getCurrentUserPhoneAction() {
+  const api = await loadApiClient();
+  const me = await api.getCurrentUser();
+  const userId = extractUserId(me);
+  if (!userId) {
+    return { ok: true, data: { hasPhone: false, phone: null } };
+  }
+  let phones = [];
+  try {
+    const payload = await api.getUserPhoneNumbers(userId);
+    phones = payload?.data || [];
+  } catch {
+    // best-effort; treat as no phone on error.
+  }
+  const primary = phones.find((p) => p.attributes?.primary) || phones[0] || null;
+  return {
+    ok: true,
+    data: { hasPhone: phones.length > 0, phone: primary?.attributes?.phone || null }
+  };
+}
+
+function formatError(error) {
+  return error?.message?.replace(/^Rootly API request failed for [^:]+:\s*/, '') || 'unknown error';
+}
+
+// Browser (OAuth) sign-ins can't manage phone numbers yet (403/404). Surface a
+// clear next step instead of the raw API error.
+function isPermissionFailure(error) {
+  const message = error?.message || '';
+  return /\b40[134]\b/.test(message) || /Not found or unauthorized/i.test(message);
+}
+
+const PHONE_BLOCKED_MESSAGE =
+  'This sign-in can’t add phone numbers. Sign in with an API token, or add your number in the Rootly app.';
+
+// Add a phone number to the signed-in user and trigger a verification SMS.
+// Returns the new phone number id so the caller can submit the code next.
+export async function startPhoneVerificationAction({ phone } = {}) {
+  // Strip spaces, parens, dashes, dots; keep digits and a leading "+". A US
+  // number works without a country code (Rootly normalizes with a US default).
+  const clean = String(phone || '').replace(/[()\s.\-]/g, '').trim();
+  if (!clean) {
+    return { ok: false, summary: 'A phone number is required.' };
+  }
+
+  const api = await loadApiClient();
+  const currentUser = await api.getCurrentUser();
+  const userId = extractUserId(currentUser);
+  if (!userId) {
+    return { ok: false, summary: 'Could not resolve the current user.' };
+  }
+
+  let phoneNumberId = null;
+  try {
+    const created = await api.createUserPhoneNumber(userId, clean);
+    phoneNumberId = created?.data?.id || null;
+  } catch (error) {
+    if (isPermissionFailure(error)) {
+      return { ok: false, summary: PHONE_BLOCKED_MESSAGE };
+    }
+    return { ok: false, summary: `Could not add the phone number: ${formatError(error)}` };
+  }
+  if (!phoneNumberId) {
+    return { ok: false, summary: 'The phone number could not be created.' };
+  }
+
+  try {
+    await api.sendPhoneVerification(phoneNumberId);
+  } catch (error) {
+    // Remove the unverified number so a retry starts clean.
+    try {
+      await api.deleteUserPhoneNumber(phoneNumberId);
+    } catch {
+      // best-effort cleanup
+    }
+    if (isPermissionFailure(error)) {
+      return { ok: false, summary: PHONE_BLOCKED_MESSAGE };
+    }
+    return { ok: false, summary: `Could not send a verification code: ${formatError(error)}` };
+  }
+
+  return {
+    ok: true,
+    summary: `Sent a verification code to ${clean}.`,
+    data: { phoneNumberId, phone: clean }
+  };
+}
+
+export async function confirmPhoneVerificationAction({ phoneNumberId, code } = {}) {
+  const cleanCode = String(code || '').trim();
+  if (!phoneNumberId) {
+    return { ok: false, summary: 'Missing the phone number to verify.' };
+  }
+  if (!cleanCode) {
+    return { ok: false, summary: 'A verification code is required.' };
+  }
+
+  const api = await loadApiClient();
+  try {
+    await api.submitPhoneVerificationCode(phoneNumberId, cleanCode);
+    return { ok: true, summary: 'Phone number verified.', data: { phoneNumberId } };
+  } catch (error) {
+    return { ok: false, summary: `Could not verify the code: ${formatError(error)}` };
+  }
+}
+
+export async function resendPhoneVerificationAction({ phoneNumberId } = {}) {
+  if (!phoneNumberId) {
+    return { ok: false, summary: 'Missing the phone number.' };
+  }
+
+  const api = await loadApiClient();
+  try {
+    await api.resendPhoneVerification(phoneNumberId);
+    return { ok: true, summary: 'Sent a new verification code.', data: { phoneNumberId } };
+  } catch (error) {
+    return { ok: false, summary: `Could not resend the code: ${formatError(error)}` };
+  }
+}