@rootly/wizard 0.1.0

package/src/cli.js

@@ -0,0 +1,199 @@
+#!/usr/bin/env node
+
+import { startInteractiveWizard } from './tui/index.js';
+import {
+  ACTIONS,
+  buildActionCatalog,
+  buildToolSpecs,
+  describeAction,
+  toStructuredError,
+  validateInput
+} from './actions/registry.js';
+
+function emitAction(result) {
+  console.log(JSON.stringify(result, null, 2));
+}
+
+function agentQuickstart() {
+  return {
+    ok: true,
+    summary: 'Rootly Wizard agent interface.',
+    data: {
+      usage: 'rootly-wizard action <name> [json]',
+      conventions: [
+        'Input is a single JSON object as the last argument; output is one JSON object on stdout.',
+        'Success: { ok:true, summary, data }. Failure: { ok:false, code, error, field?, retryable }.',
+        'Auth: set ROOTLY_TOKEN to an organization admin Rootly API key.',
+        'Add "dryRun": true to any mutating action to preview without executing.'
+      ],
+      discover: {
+        list: 'rootly-wizard action list',
+        describe: 'rootly-wizard action describe <name>',
+        tools: 'rootly-wizard action tools'
+      },
+      examples: [
+        'rootly-wizard action get-recommended-next-step',
+        'rootly-wizard action list-services',
+        'rootly-wizard action run-guided-setup \'{"teamName":"Payments"}\''
+      ]
+    }
+  };
+}
+
+async function runActionCommand() {
+  const actionName = process.argv[3];
+  const rawInput = process.argv[4];
+
+  if (!actionName || actionName === 'help') {
+    emitAction(agentQuickstart());
+    return;
+  }
+
+  if (actionName === 'list') {
+    emitAction({ ok: true, summary: 'Available actions.', data: { actions: buildActionCatalog() } });
+    return;
+  }
+
+  if (actionName === 'tools') {
+    emitAction({ ok: true, summary: 'Function-calling tool definitions.', data: { tools: buildToolSpecs() } });
+    return;
+  }
+
+  if (actionName === 'describe') {
+    const described = describeAction(rawInput);
+    if (!described) {
+      emitAction({
+        ok: false,
+        code: 'UNKNOWN_ACTION',
+        summary: `Unknown action: ${rawInput || '(missing)'}`,
+        data: { actions: Object.keys(ACTIONS) }
+      });
+      return;
+    }
+    emitAction({ ok: true, summary: `Schema for ${rawInput}.`, data: described });
+    return;
+  }
+
+  const entry = ACTIONS[actionName];
+  if (!entry) {
+    emitAction({
+      ok: false,
+      code: 'UNKNOWN_ACTION',
+      summary: `Unknown action: ${actionName || '(missing)'}`,
+      data: {
+        actions: Object.keys(ACTIONS),
+        hint: 'Run `action list` for descriptions or `action describe <name>` for input schema.'
+      }
+    });
+    return;
+  }
+
+  let inputPayload;
+  try {
+    inputPayload = rawInput ? JSON.parse(rawInput) : {};
+  } catch {
+    emitAction({
+      ok: false,
+      code: 'BAD_INPUT',
+      summary: `Could not parse input for ${actionName}.`,
+      error: 'The input argument was not valid JSON.',
+      data: null
+    });
+    return;
+  }
+
+  const invalid = validateInput(entry.input, inputPayload);
+  if (invalid) {
+    emitAction({
+      ok: false,
+      code: 'VALIDATION',
+      summary: `Invalid input for ${actionName}.`,
+      field: invalid.field,
+      error: invalid.message,
+      retryable: false,
+      data: null
+    });
+    return;
+  }
+
+  if (entry.mutates && inputPayload.dryRun === true) {
+    const { dryRun, ...input } = inputPayload;
+    emitAction({
+      ok: true,
+      code: 'DRY_RUN',
+      summary: `Dry run: ${actionName} was not executed.`,
+      data: { action: actionName, mutates: true, input }
+    });
+    return;
+  }
+
+  try {
+    emitAction(await entry.handler(inputPayload));
+  } catch (error) {
+    emitAction(toStructuredError(actionName, error));
+  }
+}
+
+function printHelp() {
+  console.log('Rootly Wizard');
+  console.log('A guided onboarding CLI for getting Rootly operational quickly.');
+  console.log('');
+  console.log('Usage:');
+  console.log('  rootly-wizard                        Start the interactive guided setup');
+  console.log('  rootly-wizard action <name> [json]   Run a single action non-interactively (JSON in/out)');
+  console.log('  rootly-wizard action list            List available actions (JSON)');
+  console.log('  rootly-wizard action describe <name> Show an action input schema (JSON)');
+  console.log('  rootly-wizard action tools           Emit function-calling tool defs (JSON)');
+  console.log('  rootly-wizard action help            Agent quickstart (JSON)');
+  console.log('  rootly-wizard help                   Show this help');
+  console.log('');
+  console.log('The interactive wizard handles sign-in, status, inspect, setup, integrations,');
+  console.log('verify, MCP setup, and disconnect from a single menu.');
+  console.log('Preferred run path: `rootly-wizard` or `npx @rootly/wizard` once published.');
+  console.log('Local development: `node ./src/cli.js`.');
+  console.log('Auth: set ROOTLY_TOKEN, or sign in on first run (browser or API key).');
+  console.log('Agents: see AGENTS.md. Pass {"dryRun": true} to any mutating action to preview.');
+}
+
+function formatTopLevelError(error) {
+  const message = error?.message || String(error);
+
+  if (/\b401\b/.test(message)) {
+    return 'Rootly rejected the token (401). Disconnect from the wizard menu, then sign in again.';
+  }
+  if (/\b403\b/.test(message)) {
+    return 'Rootly denied access (403). This wizard expects an admin, organization-wide API key — check your token scope.';
+  }
+  if (error?.name === 'TimeoutError' || error?.name === 'AbortError' || /timed out|aborted/i.test(message)) {
+    return 'A Rootly API request timed out. Check your network connection and try again.';
+  }
+
+  return message;
+}
+
+async function main() {
+  const entry = process.argv[2];
+
+  if (entry === 'action') {
+    await runActionCommand();
+    return;
+  }
+
+  if (entry === 'help' || entry === '--help' || entry === '-h') {
+    printHelp();
+    return;
+  }
+
+  if (!process.stdin.isTTY || !process.stdout.isTTY) {
+    console.log('An interactive terminal is required. Run this in a normal shell session.');
+    process.exitCode = 1;
+    return;
+  }
+
+  await startInteractiveWizard();
+}
+
+main().catch((error) => {
+  console.error(formatTopLevelError(error));
+  process.exitCode = 1;
+});

package/src/detect-state.js

@@ -0,0 +1,232 @@
+function toIdSet(items = []) {
+  return new Set(items.map((item) => item.id));
+}
+
+function userTeamIds(userPayload) {
+  return userPayload?.data?.relationships?.teams?.data?.map((team) => team.id) || [];
+}
+
+function currentWorkspaceId(userPayload) {
+  return userPayload?.data?.relationships?.current_team?.data?.id || null;
+}
+
+function inferredWorkspaceName(userPayload) {
+  const explicitName =
+    userPayload?.data?.attributes?.current_team_name ||
+    userPayload?.data?.attributes?.team_name ||
+    null;
+
+  if (explicitName) {
+    return explicitName;
+  }
+
+  const decorated = userPayload?.data?.attributes?.full_name_with_team || '';
+  const match = decorated.match(/^\[(.+?)\]/);
+  return match?.[1] || null;
+}
+
+function getSlackId(userPayload) {
+  return userPayload?.data?.attributes?.slack_id || null;
+}
+
+function getRelationshipIds(entity, relationshipName) {
+  return entity?.relationships?.[relationshipName]?.data?.map((item) => item.id) || [];
+}
+
+function getTeamAttributes(team) {
+  return team?.attributes || {};
+}
+
+function countSlackCoverageSignals(attrs = {}) {
+  const scalarSignals = [
+    attrs.slack_channel_id,
+    attrs.slack_channel_name,
+    attrs.slack_channel,
+    attrs.slack_group_id,
+    attrs.slack_workspace_id
+  ].filter((value) => value !== null && value !== undefined && value !== '');
+
+  const arraySignals = [
+    ...(Array.isArray(attrs.slack_channels) ? attrs.slack_channels : []),
+    ...(Array.isArray(attrs.slack_aliases) ? attrs.slack_aliases : [])
+  ];
+
+  return scalarSignals.length + arraySignals.length;
+}
+
+function count(items) {
+  return Array.isArray(items) ? items.length : 0;
+}
+
+function summarizeStage(doneCount, totalCount) {
+  if (doneCount <= 0) {
+    return 'needed';
+  }
+
+  if (doneCount >= totalCount) {
+    return 'done';
+  }
+
+  return 'in-progress';
+}
+
+function teamCoverageLabel(doneCount, totalCount) {
+  if (totalCount <= 0) {
+    return 'needed';
+  }
+
+  if (doneCount <= 0) {
+    return 'needed';
+  }
+
+  if (doneCount >= totalCount) {
+    return 'done';
+  }
+
+  return 'in-progress';
+}
+
+export function detectOnboardingState({ userPayload, teamsPayload, schedulesPayload, escalationPoliciesPayload, authMode = 'stored-token' }) {
+  const user = userPayload?.data?.attributes || {};
+  const teams = teamsPayload?.data || [];
+  const schedules = schedulesPayload?.data || [];
+  const escalationPolicies = escalationPoliciesPayload?.data || [];
+
+  const teamsById = new Map(teams.map((team) => [team.id, team]));
+  const workspaceId = currentWorkspaceId(userPayload);
+  const workspace = workspaceId ? teamsById.get(workspaceId) : null;
+  const currentUserTeamIds = userTeamIds(userPayload);
+  const currentUserTeams = currentUserTeamIds.map((id) => teamsById.get(id)).filter(Boolean);
+  const teamsWithSchedules = teams.filter((team) => count(getRelationshipIds(team, 'schedules')) > 0);
+  const teamsWithEscalationPolicies = teams.filter((team) => count(getRelationshipIds(team, 'escalation_policies')) > 0);
+  const teamsWithSlack = teams.filter((team) => {
+    const attrs = getTeamAttributes(team);
+    return countSlackCoverageSignals(attrs) > 0;
+  });
+  const alertableTeams = teams.filter((team) => {
+    const attrs = getTeamAttributes(team);
+    const teamSchedules = getRelationshipIds(team, 'schedules');
+    const teamPolicies = getRelationshipIds(team, 'escalation_policies');
+
+    return teamSchedules.length > 0 || teamPolicies.length > 0 || Boolean(attrs.alert_source_count || attrs.alert_sources_count);
+  });
+
+  const hasTeams = teams.length > 0;
+  const hasAnySchedules = schedules.length > 0;
+  const hasAnyEscalationPolicies = escalationPolicies.length > 0;
+  const hasSlack = Boolean(getSlackId(userPayload));
+  const hasUserTeam = currentUserTeams.length > 0;
+  const userHasSchedule = currentUserTeams.some((team) => getRelationshipIds(team, 'schedules').length > 0);
+  const userHasEscalationPolicy = currentUserTeams.some((team) => getRelationshipIds(team, 'escalation_policies').length > 0);
+  const userTeamsWithSlack = currentUserTeams.filter((team) => {
+    const attrs = getTeamAttributes(team);
+    return countSlackCoverageSignals(attrs) > 0;
+  });
+  const hasAnySlackConfigured = hasSlack || teamsWithSlack.length > 0 || userTeamsWithSlack.length > 0;
+  const hasAnyAlertingReadyTeam = alertableTeams.length > 0;
+  const hasAnyTeamMembership = currentUserTeams.length > 0;
+  const teamCount = teams.length;
+  const teamsWithSchedulesCount = teamsWithSchedules.length;
+  const teamsWithEscalationPoliciesCount = teamsWithEscalationPolicies.length;
+  const teamsWithSlackCount = teamsWithSlack.length;
+  const teamsWithMembersCount = teams.filter((team) => count(getRelationshipIds(team, 'users')) > 0).length;
+
+  const nextBestAction = !hasTeams
+    ? 'create-team'
+    : teamsWithMembersCount === 0
+      ? 'invite-team-members'
+      : teamsWithSchedulesCount === 0
+        ? 'create-schedule'
+        : teamsWithEscalationPoliciesCount === 0
+          ? 'create-escalation-policy'
+          : !hasAnyAlertingReadyTeam
+            ? 'hook-up-monitor'
+            : 'run-guided-setup';
+
+  const steps = {
+    createTeam: hasTeams ? 'done' : 'needed',
+    inviteTeamMembers: teamsWithMembersCount > 0 ? 'done' : 'needed',
+    createSchedule: teamsWithSchedulesCount > 0 ? 'done' : 'needed',
+    createEscalationPolicy: teamsWithEscalationPoliciesCount > 0 ? 'done' : 'needed',
+    hookUpMonitor: hasAnyAlertingReadyTeam ? 'done' : 'needed',
+    testPage: hasAnyAlertingReadyTeam ? 'maybe-needed' : 'blocked',
+    connectSlack: hasAnySlackConfigured ? 'maybe-needed' : 'needed',
+    createTestIncident: 'maybe-needed'
+  };
+
+  const readiness = {
+    workspaceSetup: summarizeStage(
+      [hasTeams].filter(Boolean).length,
+      1
+    ),
+    groupSetup: teamCoverageLabel(
+      teamsWithMembersCount + teamsWithSchedulesCount + teamsWithEscalationPoliciesCount,
+      teamCount * 3
+    ),
+    alertingSetup: summarizeStage(
+      [hasAnyAlertingReadyTeam, hasAnySchedules, hasAnyEscalationPolicies].filter(Boolean).length,
+      3
+    ),
+    incidentSetup: teamsWithSlackCount > 0 || hasSlack ? 'in-progress' : 'needed'
+  };
+
+  return {
+    auth: {
+      valid: true,
+      mode: authMode
+    },
+    user: {
+      id: userPayload?.data?.id || null,
+      email: user.email || null,
+      name: user.full_name || user.name || null,
+      slackConnected: hasSlack,
+      teams: currentUserTeams.map((team) => ({
+        id: team.id,
+        name: team.attributes?.name,
+        slug: team.attributes?.slug
+      }))
+    },
+    teams: {
+      workspace: {
+        id: workspace?.id || workspaceId || null,
+        name: workspace?.attributes?.name || inferredWorkspaceName(userPayload),
+        slug: workspace?.attributes?.slug || null
+      },
+      total: teams.length,
+      hasTeams,
+      hasAnyTeamMembership,
+      all: teams.map((team) => ({
+        id: team.id,
+        name: team.attributes?.name,
+        userIds: getRelationshipIds(team, 'users'),
+        memberCount: count(team?.relationships?.users?.data),
+        scheduleCount: count(team?.relationships?.schedules?.data),
+        escalationPolicyCount: count(team?.relationships?.escalation_policies?.data)
+      })),
+      userTeams: currentUserTeams.map((team) => ({
+        id: team.id,
+        name: team.attributes?.name,
+        scheduleCount: count(team?.relationships?.schedules?.data),
+        escalationPolicyCount: count(team?.relationships?.escalation_policies?.data)
+      })),
+      hasAnySchedules,
+      hasAnyEscalationPolicies,
+      hasAnySlackConfigured,
+      hasAnyAlertingReadyTeam,
+      teamsWithMembers: teamsWithMembersCount,
+      teamsWithSchedules: teamsWithSchedules.length,
+      teamsWithEscalationPolicies: teamsWithEscalationPolicies.length,
+      teamsWithSlack: teamsWithSlack.length
+    },
+    onboarding: {
+      completed:
+        nextBestAction === 'run-guided-setup' &&
+        hasAnySchedules &&
+        hasAnyEscalationPolicies &&
+        hasAnyAlertingReadyTeam,
+      nextBestAction,
+      readiness,
+      steps
+    }
+  };
+}

package/src/format.js

@@ -0,0 +1,43 @@
+// Wrap a URL in an OSC 8 terminal hyperlink so supporting terminals render it
+// as a clickable link. Keeps the URL itself as the visible text by default, so
+// it stays readable/copyable where hyperlinks aren't supported. Non-TTY output
+// (pipes, CI) returns the plain label.
+export function hyperlink(url, label = url) {
+  if (!process.stdout || !process.stdout.isTTY) return label;
+  const OSC = ']8;;';
+  const BEL = '';
+  return `${OSC}${url}${BEL}${label}${OSC}${BEL}`;
+}
+
+// Format an E.164-ish phone number for display. US/Canada (+1 + 10 digits)
+// becomes +1 (415) 706-8600; anything else is returned as-is.
+export function formatPhone(raw) {
+  const s = String(raw || '').trim();
+  const m = s.match(/^\+1(\d{3})(\d{3})(\d{4})$/);
+  return m ? `+1 (${m[1]}) ${m[2]}-${m[3]}` : s;
+}
+
+// Turn a raw API/action error string into a short, human phrase suitable for a
+// result screen. Passes already-clean text through unchanged, so it's safe to
+// wrap any failure summary with it.
+export function friendlyError(raw) {
+  const s = String(raw || '');
+  if (/already been taken|already exists/i.test(s)) return 'This already exists — it looks set up already.';
+  if (/not found or unauthorized/i.test(s)) return 'Not permitted by this sign-in.';
+  if (/\b429\b|rate limit/i.test(s)) return 'Rate limited — try again shortly.';
+  // Pull a human detail out of a JSON error body if present.
+  const brace = s.indexOf('{');
+  if (brace !== -1) {
+    try {
+      const body = JSON.parse(s.slice(brace));
+      const first = Array.isArray(body?.errors) ? body.errors[0] : null;
+      const detail = first?.detail || first?.title
+        || (body && typeof body === 'object' ? Object.values(body).flat()[0] : null);
+      if (detail) return String(detail);
+    } catch {
+      // fall through
+    }
+  }
+  // Strip a leading "NNN - " HTTP status prefix if present.
+  return s.replace(/^\d{3}\s*-\s*/, '').trim() || 'Something went wrong. Please try again.';
+}