@rootly/wizard 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Rootly
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,131 @@
+# Rootly Wizard
+
+Get your Rootly workspace from empty to incident-ready in minutes — without clicking through every setup screen.
+
+Rootly Wizard is a guided command-line setup tool. It walks you through creating a team, putting people on call, wiring up escalation and alerting, creating a status page, and firing a real test alert and incident — including a phone call to whoever is on call — so you can see the whole flow end to end.
+
+![Rootly Wizard welcome screen](assets/welcome-screen.png)
+
+```bash
+npx @rootly/wizard
+```
+
+## Requirements
+
+- **Node.js 18 or newer**
+- A **Rootly account** (don't have one? the wizard can hand you off to sign up)
+- Sign in with a **browser (OAuth)** or a **Rootly API token** (see [Signing in](#signing-in))
+- A terminal (macOS, Linux, or Windows)
+
+## Quick start
+
+Run the wizard:
+
+```bash
+npx @rootly/wizard
+```
+
+Sign in (browser or API token — your session is stored securely in your OS keychain), then land on the main menu:
+
+- **Recommended setup** — set everything up at once and see a test alert (that pages on-call) + a test incident
+- **General setup** — pick any individual task (teams, on-call, status pages, integrations, and more)
+
+Your sign-in is remembered, so the next run takes you straight to the menu.
+
+## Signing in
+
+From the sign-in screen you can:
+
+- **Browser sign-in** — authorize in your browser (OAuth).
+- **API token** — paste a Rootly API token. **Recommended for the full experience** (see [Known limitations](#known-limitations)).
+- **Create a Rootly account** — opens signup in your browser. Account creation is web-only (it's protected by a CAPTCHA), so the wizard hands off to the website, then you return and sign in.
+
+To create an **API token**:
+
+1. Log in to Rootly.
+2. Go to **Organization Settings → API Keys**.
+3. Click **Generate New API Key**, name it, and copy the token.
+
+**Which key type?** Use a **Global** key with write access (teams, schedules, escalation, alerts, incidents) so the wizard can complete setup, or a **Personal** key if your account can already manage those.
+
+Docs: <https://docs.rootly.com/api-reference/overview>
+
+Your token/session is stored in your operating system's keychain. You can also provide a token via the `ROOTLY_TOKEN` environment variable:
+
+```bash
+ROOTLY_TOKEN=rootly_xxx npx @rootly/wizard
+```
+
+On exit, the wizard asks whether to keep the saved sign-in or delete it from your keychain (it keeps it by default).
+
+## What you can do
+
+### Recommended setup (all-in-one)
+
+The fastest path. In one flow it will:
+
+1. Create a team (or reuse one you're already on)
+2. Let you pick who joins the team and the on-call rotation
+3. Create an on-call schedule
+4. Create an escalation policy that pages the on-call schedule
+5. Add an alert source
+6. Create a public status page (and choose which components appear on it)
+7. Fire a **test alert** that **pages the on-call person** (a real call/text)
+8. Open a **test incident** (with a link to its Slack channel, if Slack is connected)
+
+Before it runs, you can add and verify a **phone number** and connect **Slack** so the test alert actually reaches you. Anything that already exists is reused, so it's safe to re-run.
+
+### General setup
+
+Jump to any individual task:
+
+- **Teams & members** — create teams, add members from your directory
+- **On-call** — schedules and escalation policies
+- **Status page** — create a public status page and pick which components (services) appear on it
+- **Integrations** — Slack, and alert-source handoffs (Datadog, Grafana, Sentry, PagerDuty, Opsgenie)
+- **Verify** — send a test alert (pages on-call) or create a test incident
+- **Inspect** — review your current teams, schedules, and coverage
+- **MCP / IDE** — configure the Rootly MCP server for your editor or AI agent
+- **Chat with us** — talk to our founder JJ or book a demo with sales
+
+### MCP / IDE setup
+
+The wizard can write Rootly MCP server config for **Codex** (preview the config or apply it directly).
+
+## Scripting (advanced)
+
+Every setup step is also available non-interactively as a JSON-in/JSON-out action — handy for automation or AI agents:
+
+```bash
+rootly-wizard action list                 # list available actions
+rootly-wizard action describe <name>      # show an action's inputs
+rootly-wizard action get-recommended-next-step
+rootly-wizard action one-shot-setup '{"teamName":"Payments"}'
+```
+
+Add `"dryRun": true` to any setup action to preview it without making changes.
+
+## Known limitations
+
+The wizard is under active development. A few things to know:
+
+- **Use an API token for the full experience.** Browser (OAuth) sign-in can create teams, schedules, escalation policies, alert sources, status pages, alerts, and incidents — but it currently can't list your user directory, so **picking other teammates falls back to just you** (a server-side fix is in progress). An API token has no such limit.
+- **Account creation is browser-only** (CAPTCHA / spam protection), so the wizard hands off to the website for signup.
+- **Clickable links and the logo art** depend on your terminal's capabilities; where they aren't supported, the wizard falls back to plain text.
+
+## Troubleshooting
+
+- **"Sign in to Rootly" keeps appearing** — your token may be missing or invalid. Generate a fresh key (Organization Settings → API Keys) and re-enter it, or sign in with your browser.
+- **Setup steps are skipped or blocked** — the sign-in needs write access. Use a Global API token with the relevant permissions, or see [Known limitations](#known-limitations).
+- **Nothing happens / wrong screen** — make sure you're on Node.js 18+ and running in an interactive terminal.
+
+## Development
+
+From a clone of this repo:
+
+```bash
+node ./src/cli.js     # run the wizard locally
+npm test              # run the test suite
+```
+
+(Use `node ./src/cli.js` rather than `npm start` for demos — `npm start` echoes the underlying command before launching.)

package/package.json

@@ -0,0 +1,47 @@
+{
+  "name": "@rootly/wizard",
+  "version": "0.1.0",
+  "description": "Guided Rootly setup CLI",
+  "license": "MIT",
+  "type": "module",
+  "bin": {
+    "rootly-wizard": "./src/cli.js"
+  },
+  "files": [
+    "src",
+    "assets",
+    "README.md"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Rootly-AI-Labs/rootly-wizard.git"
+  },
+  "homepage": "https://github.com/Rootly-AI-Labs/rootly-wizard#readme",
+  "bugs": {
+    "url": "https://github.com/Rootly-AI-Labs/rootly-wizard/issues"
+  },
+  "keywords": [
+    "rootly",
+    "incident-management",
+    "on-call",
+    "cli",
+    "setup",
+    "wizard"
+  ],
+  "scripts": {
+    "start": "node ./src/cli.js",
+    "test": "node --test",
+    "prepublishOnly": "npm test"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "ink": "^7.0.5",
+    "keytar": "^7.9.0",
+    "react": "^19.2.7"
+  }
+}

package/src/actions/guided.js

@@ -0,0 +1,87 @@
+import {
+  createAlertSourceAction,
+  createEscalationPolicyAction,
+  createScheduleAction,
+  createTeamAction
+} from './setup.js';
+
+function stepError(error) {
+  return error?.message?.replace(/^Rootly API request failed for [^:]+:\s*/, '') || 'unknown error';
+}
+
+export async function runGuidedSetupAction({
+  teamName = 'Rootly team',
+  description = 'Created during Rootly setup',
+  memberEmails = [],
+  handoffTime = '09:00',
+  repeatCount = 1,
+  includeAlertSource = true,
+  enableAlertsAndBroadcast = true
+} = {}) {
+  const steps = [];
+  const data = {
+    team: null,
+    schedule: null,
+    escalationPolicy: null,
+    alertSource: null,
+    matchedUsers: [],
+    steps
+  };
+
+  // The team is the anchor for everything else, so a team failure is fatal.
+  let teamResult;
+  try {
+    teamResult = await createTeamAction({ name: teamName, description, memberEmails, enableAlertsAndBroadcast });
+    data.team = { id: teamResult.data.id, name: teamResult.data.name };
+    data.matchedUsers = teamResult.data.matchedUsers;
+    steps.push({ step: 'create-team', ok: true, id: teamResult.data.id, error: null });
+  } catch (error) {
+    steps.push({ step: 'create-team', ok: false, id: null, error: stepError(error) });
+    return {
+      ok: false,
+      code: 'GUIDED_SETUP_FAILED',
+      summary: 'Guided setup could not create the first team.',
+      data
+    };
+  }
+
+  const teamId = teamResult.data.id;
+  const memberIds = teamResult.data.memberIds;
+
+  try {
+    const schedule = await createScheduleAction({ teamId, name: `${teamName} On-Call`, handoffTime, memberIds });
+    data.schedule = { id: schedule.data.scheduleId };
+    steps.push({ step: 'create-schedule', ok: true, id: schedule.data.scheduleId, error: null });
+  } catch (error) {
+    steps.push({ step: 'create-schedule', ok: false, id: null, error: stepError(error) });
+  }
+
+  try {
+    const escalation = await createEscalationPolicyAction({
+      teamId,
+      name: `${teamName} Default Escalation`,
+      repeatCount,
+      createDefaultPath: Boolean(data.schedule)
+    });
+    data.escalationPolicy = { id: escalation.data.id, pathCreated: escalation.data.pathCreated };
+    steps.push({ step: 'create-escalation-policy', ok: true, id: escalation.data.id, error: escalation.data.pathError });
+  } catch (error) {
+    steps.push({ step: 'create-escalation-policy', ok: false, id: null, error: stepError(error) });
+  }
+
+  if (includeAlertSource) {
+    try {
+      const source = await createAlertSourceAction({ teamId, name: `${teamName} Generic webhook` });
+      data.alertSource = { id: source.data.id, webhookEndpoint: source.data.webhookEndpoint };
+      steps.push({ step: 'create-alert-source', ok: true, id: source.data.id, error: null });
+    } catch (error) {
+      steps.push({ step: 'create-alert-source', ok: false, id: null, error: stepError(error) });
+    }
+  }
+
+  return {
+    ok: true,
+    summary: `Ran guided setup for ${teamName}.`,
+    data
+  };
+}

package/src/actions/inspect.js

@@ -0,0 +1,341 @@
+import { getActiveToken, isServiceAccount, loadApiClient, loadOnboardingState } from '../runtime.js';
+
+// Services + functionalities a status page can show as components. Values are
+// encoded "service:<id>" / "functionality:<id>" so the picker can split them.
+export async function getStatusPageComponentsAction() {
+  const api = await loadApiClient();
+  const [services, functionalities] = await Promise.all([
+    api.listServices().catch(() => ({ data: [] })),
+    api.listFunctionalities().catch(() => ({ data: [] }))
+  ]);
+  const components = [
+    ...((services?.data) || []).map((s) => ({ label: `${s.attributes?.name || s.id} · service`, value: `service:${s.id}` })),
+    ...((functionalities?.data) || []).map((f) => ({ label: `${f.attributes?.name || f.id} · functionality`, value: `functionality:${f.id}` }))
+  ];
+  return { ok: true, data: { components } };
+}
+
+// Create a custom status-page component. A typed-in component becomes a new
+// Service (each service carries its own operational status, so it renders as a
+// component on the public page), then gets added to the page by id. Returns the
+// encoded component for the picker.
+export async function createCustomComponentAction({ name }) {
+  const clean = String(name || '').trim();
+  if (!clean) {
+    return { ok: false, summary: 'A component name is required.' };
+  }
+  const api = await loadApiClient();
+  const payload = await api.createService({ name: clean });
+  const id = payload?.data?.id;
+  if (!id) {
+    return { ok: false, summary: 'Rootly did not return the new component.' };
+  }
+  return {
+    ok: true,
+    data: {
+      id,
+      name: payload?.data?.attributes?.name || clean,
+      component: { label: `${payload?.data?.attributes?.name || clean} · service`, value: `service:${id}` }
+    }
+  };
+}
+
+export async function getStatusAction() {
+  const state = await loadOnboardingState();
+  if (!state) {
+    return {
+      ok: false,
+      code: 'NO_AUTH',
+      summary: 'No auth context found.',
+      data: null
+    };
+  }
+
+  return {
+    ok: true,
+    summary: 'Loaded workspace status.',
+    data: {
+      nextBestAction: state.onboarding.nextBestAction,
+      workspace: state.teams.workspace?.name || state.teams.workspace?.slug || 'Connected Rootly account',
+      teams: state.teams.total,
+      teamsWithMembers: state.teams.teamsWithMembers,
+      teamsWithSchedules: state.teams.teamsWithSchedules,
+      teamsWithEscalationPolicies: state.teams.teamsWithEscalationPolicies,
+      teamsWithSlackSignals: state.teams.teamsWithSlack,
+      readiness: state.onboarding.readiness
+    }
+  };
+}
+
+export async function getReadinessAction() {
+  const state = await loadOnboardingState();
+  if (!state) {
+    return {
+      ok: false,
+      code: 'NO_AUTH',
+      summary: 'No auth context found.',
+      data: null
+    };
+  }
+
+  return {
+    ok: true,
+    summary: 'Loaded onboarding readiness.',
+    data: {
+      nextBestAction: state.onboarding.nextBestAction,
+      workspace: state.teams.workspace,
+      onboarding: state.onboarding,
+      teams: state.teams
+    }
+  };
+}
+
+export async function getTeamsAction() {
+  const state = await loadOnboardingState();
+  if (!state) {
+    return {
+      ok: false,
+      code: 'NO_AUTH',
+      summary: 'No auth context found.',
+      data: null
+    };
+  }
+
+  return {
+    ok: true,
+    summary: 'Loaded teams.',
+    data: {
+      workspace: state.teams.workspace,
+      summary: {
+        total: state.teams.total,
+        teamsWithMembers: state.teams.teamsWithMembers,
+        teamsWithSchedules: state.teams.teamsWithSchedules,
+        teamsWithEscalationPolicies: state.teams.teamsWithEscalationPolicies,
+        teamsWithSlackSignals: state.teams.teamsWithSlack
+      },
+      teams: state.teams.all
+    }
+  };
+}
+
+export async function getSchedulesAction() {
+  const token = await getActiveToken();
+  if (!token) {
+    return {
+      ok: false,
+      code: 'NO_AUTH',
+      summary: 'No auth context found.',
+      data: null
+    };
+  }
+
+  const api = await loadApiClient();
+  const schedulesPayload = await api.listSchedules();
+  const schedules = schedulesPayload?.data || [];
+
+  return {
+    ok: true,
+    summary: 'Loaded schedules.',
+    data: {
+      summary: {
+        total: schedules.length,
+        schedulesWithCoverage: schedules.filter((schedule) => schedule?.attributes?.all_time_coverage).length,
+        schedulesWithTeams: schedules.filter((schedule) =>
+          Array.isArray(schedule?.attributes?.owner_group_ids) && schedule.attributes.owner_group_ids.length > 0
+        ).length
+      },
+      schedules
+    }
+  };
+}
+
+export async function getEscalationPoliciesAction() {
+  const token = await getActiveToken();
+  if (!token) {
+    return {
+      ok: false,
+      code: 'NO_AUTH',
+      summary: 'No auth context found.',
+      data: null
+    };
+  }
+
+  const api = await loadApiClient();
+  const policiesPayload = await api.listEscalationPolicies();
+  const policies = policiesPayload?.data || [];
+
+  return {
+    ok: true,
+    summary: 'Loaded escalation policies.',
+    data: {
+      summary: {
+        total: policies.length,
+        policiesWithTeams: policies.filter((policy) =>
+          Array.isArray(policy?.attributes?.group_ids) && policy.attributes.group_ids.length > 0
+        ).length,
+        repeatingPolicies: policies.filter((policy) => (policy?.attributes?.repeat_count ?? 0) > 0).length
+      },
+      policies
+    }
+  };
+}
+
+async function listResourceAction(method, label, mapItem) {
+  const token = await getActiveToken();
+  if (!token) {
+    return {
+      ok: false,
+      code: 'NO_AUTH',
+      summary: 'No auth context found.',
+      data: null
+    };
+  }
+
+  const api = await loadApiClient();
+  const payload = await api[method]();
+  const items = (payload?.data || []).map(mapItem);
+
+  return {
+    ok: true,
+    summary: `Loaded ${label}.`,
+    data: { total: items.length, items }
+  };
+}
+
+export async function getTeamMembersAction({ teamId } = {}) {
+  const token = await getActiveToken();
+  if (!token) {
+    return { ok: false, code: 'NO_AUTH', summary: 'No auth context found.', data: null };
+  }
+
+  const api = await loadApiClient();
+  const payload = await api.getTeam(teamId);
+  const team = payload?.data;
+  const usersById = new Map((payload?.included || [])
+    .filter((record) => record.type === 'users')
+    .map((record) => [record.id, record]));
+
+  const members = (team?.relationships?.users?.data || []).map(({ id }) => {
+    const record = usersById.get(id);
+    return {
+      id,
+      email: record?.attributes?.email || null,
+      name: record?.attributes?.full_name || record?.attributes?.name || null,
+      serviceAccount: isServiceAccount(record)
+    };
+  });
+
+  return {
+    ok: true,
+    summary: `Loaded members for team ${teamId}.`,
+    data: {
+      teamId,
+      teamName: team?.attributes?.name || teamId,
+      total: members.length,
+      members
+    }
+  };
+}
+
+function usersLookupUnavailable(error) {
+  const message = error?.message || '';
+  return message.includes('/v1/users') && message.includes('404');
+}
+
+export async function getDirectoryUsersAction() {
+  const token = await getActiveToken();
+  if (!token) {
+    return { ok: false, code: 'NO_AUTH', summary: 'No auth context found.', data: null };
+  }
+
+  const api = await loadApiClient();
+
+  // Limited OAuth sessions can't read /v1/users; flag that so the caller can
+  // fall back gracefully instead of failing.
+  let allUsers = [];
+  let userLookupUnavailable = false;
+  try {
+    allUsers = await api.listAllUsers();
+  } catch (error) {
+    if (usersLookupUnavailable(error)) {
+      userLookupUnavailable = true;
+    } else {
+      throw error;
+    }
+  }
+
+  const users = allUsers
+    .filter((record) => !isServiceAccount(record))
+    .map((record) => ({
+      id: String(record.id),
+      name: record?.attributes?.full_name || record?.attributes?.name || null,
+      email: record?.attributes?.email || null
+    }));
+
+  return {
+    ok: true,
+    summary: `Loaded ${users.length} directory user(s).`,
+    data: { total: users.length, users, userLookupUnavailable }
+  };
+}
+
+export async function getAddableTeamMembersAction({ teamId } = {}) {
+  const token = await getActiveToken();
+  if (!token) {
+    return { ok: false, code: 'NO_AUTH', summary: 'No auth context found.', data: null };
+  }
+
+  const api = await loadApiClient();
+  const teamPayload = await api.getTeam(teamId);
+  const existing = new Set((teamPayload?.data?.attributes?.user_ids || []).map((id) => String(id)));
+
+  // Some sign-ins (notably limited OAuth sessions) cannot read /v1/users.
+  // Surface that as a flag so the caller can fall back to inviting by email.
+  let allUsers = [];
+  let userLookupUnavailable = false;
+  try {
+    allUsers = await api.listAllUsers();
+  } catch (error) {
+    if (usersLookupUnavailable(error)) {
+      userLookupUnavailable = true;
+    } else {
+      throw error;
+    }
+  }
+
+  const addable = allUsers
+    .filter((record) => !isServiceAccount(record))
+    .map((record) => ({
+      id: String(record.id),
+      name: record?.attributes?.full_name || record?.attributes?.name || null,
+      email: record?.attributes?.email || null
+    }))
+    .filter((user) => !existing.has(user.id));
+
+  return {
+    ok: true,
+    summary: `Loaded addable members for team ${teamId}.`,
+    data: {
+      teamId,
+      teamName: teamPayload?.data?.attributes?.name || teamId,
+      total: addable.length,
+      addable,
+      userLookupUnavailable
+    }
+  };
+}
+
+const byName = (record) => ({
+  id: record.id,
+  name: record?.attributes?.name || record?.attributes?.slug || record.id
+});
+
+export const getServicesAction = () => listResourceAction('listServices', 'services', byName);
+export const getSeveritiesAction = () => listResourceAction('listSeverities', 'severities', byName);
+export const getEnvironmentsAction = () => listResourceAction('listEnvironments', 'environments', byName);
+export const getIncidentTypesAction = () => listResourceAction('listIncidentTypes', 'incident types', byName);
+export const getUsersAction = () => listResourceAction('listUsers', 'users', (record) => ({
+  id: record.id,
+  email: record?.attributes?.email || null,
+  name: record?.attributes?.full_name || record?.attributes?.name || null
+}));