premanmcp 0.4.0 → 0.7.0

package/bin/integrations.js

@@ -0,0 +1,367 @@
+/**
+ * Connect AWS, GitHub and Slack from the terminal.
+ *
+ * Each of these already had a backend that hands back a URL and a way to ask
+ * whether the customer finished. What was missing was anywhere to drive them
+ * except the dashboard, which meant a terminal-first user had to stop, find the
+ * web app, and hunt for three different settings screens before PreMan could
+ * show them anything.
+ *
+ * The shape is the same for all three because the constraint is the same: the
+ * customer's session with AWS, GitHub or Slack lives in their browser, not in
+ * this process. So we ask the backend for a URL, open it, and poll our own API
+ * until the other side reports the connection exists. Nothing is copied back by
+ * hand, and no third-party credential ever touches the terminal.
+ */
+
+import { spawn } from "node:child_process";
+
+import {
+  assertOk,
+  callBackendJson,
+  frontendUrl,
+  promptText,
+  resolveApiKey,
+} from "./shared.js";
+
+const POLL_INTERVAL_MS = 3000;
+const POLL_TIMEOUT_MS = 300000;
+
+/**
+ * Colour only when someone is actually watching.
+ *
+ * Escape codes in piped output end up in log files and CI transcripts as
+ * literal noise, and NO_COLOR is the standard way to ask us not to. The mark
+ * itself still prints in both cases -- it carries the meaning, the colour only
+ * makes it quicker to find.
+ */
+const USE_COLOR = Boolean(process.stdout.isTTY) && !process.env.NO_COLOR;
+
+function paint(code, text) {
+  return USE_COLOR ? `[${code}m${text}` : text;
+}
+
+export const MARK = {
+  ok: () => paint("32", "✓"),
+  skip: () => paint("90", "○"),
+  fail: () => paint("31", "✗"),
+};
+
+/** A finished step, marked so it can be found at a glance. */
+export function connected(message) {
+  process.stdout.write(`${MARK.ok()} ${message}\n`);
+}
+
+/** Open a URL in the customer's default browser, best effort. */
+export function openUrl(url) {
+  const command =
+    process.platform === "darwin" ? "open" : process.platform === "win32" ? "start" : "xdg-open";
+  try {
+    const child = spawn(command, [url], {
+      stdio: "ignore",
+      detached: true,
+      shell: process.platform === "win32",
+    });
+    child.unref();
+    return true;
+  } catch {
+    // Headless boxes and locked-down shells are normal. The URL is printed
+    // either way, so this is a convenience, never the only path.
+    return false;
+  }
+}
+
+function present(url, what) {
+  process.stdout.write(`\n  ${url}\n\n`);
+  if (openUrl(url)) process.stdout.write(`Opened ${what} in your browser.\n`);
+  else process.stdout.write(`Open the link above to ${what}.\n`);
+}
+
+/**
+ * Raised by a poll that will never succeed, however long we wait.
+ *
+ * Distinct from an ordinary failed poll because the two need opposite
+ * handling: a network blip while the customer is in another tab should be
+ * ignored, but a stack deployed into the wrong AWS account will report the
+ * same answer forever, and waiting five minutes to say so is five minutes of
+ * the customer believing it might still work.
+ */
+export class Unrecoverable extends Error {}
+
+/**
+ * Poll ``check`` until it reports done.
+ *
+ * Returns the truthy value from ``check``, or null on timeout. Ordinary
+ * exceptions are swallowed and retried; :class:`Unrecoverable` stops the wait.
+ */
+async function waitFor(label, check) {
+  const deadline = Date.now() + POLL_TIMEOUT_MS;
+  process.stdout.write(`Waiting for ${label}`);
+  while (Date.now() < deadline) {
+    try {
+      const done = await check();
+      if (done) {
+        process.stdout.write(" done.\n");
+        return done;
+      }
+    } catch (err) {
+      if (err instanceof Unrecoverable) {
+        process.stdout.write("\n");
+        throw err;
+      }
+      /* keep waiting; the customer is elsewhere */
+    }
+    process.stdout.write(".");
+    await new Promise((resolve) => setTimeout(resolve, POLL_INTERVAL_MS));
+  }
+  process.stdout.write("\n");
+  return null;
+}
+
+function requireKey(args) {
+  const apiKey = resolveApiKey(args);
+  if (!apiKey) {
+    throw new Error("Not signed in. Run 'preman login' first.");
+  }
+  return apiKey;
+}
+
+// ---------------------------------------------------------------------------
+// AWS
+// ---------------------------------------------------------------------------
+
+export async function awsCommand(args) {
+  const token = requireKey(args);
+
+  const accountId = (
+    args.value("--account", "") || (await promptText("AWS account ID (12 digits): "))
+  ).trim();
+  const region = args.value("--region", "us-east-1");
+
+  const created = await callBackendJson(args, "POST", "/aws-links", {
+    token,
+    json: { aws_account_id: accountId, console_region: region },
+  });
+  assertOk(created, "create AWS connection");
+
+  const setup = created.setup || {};
+  process.stdout.write("\nThis grants PreMan read-only access to:\n");
+  for (const grant of setup.grants || []) process.stdout.write(`  - ${grant}\n`);
+
+  if (setup.quick_create_url) {
+    present(setup.quick_create_url, "create the CloudFormation stack");
+    process.stdout.write("Tick the IAM acknowledgement, then click Create stack.\n");
+  } else {
+    // No hosted template in this deployment: the CLI path still works.
+    process.stdout.write(`\nRun this to create the role:\n\n  ${setup.cli_command}\n\n`);
+  }
+
+  const linkId = created.link?.id;
+  let verified;
+  try {
+    verified = await waitFor("the stack", async () => {
+      const result = await callBackendJson(args, "POST", `/aws-links/${linkId}/verify`, {
+        token,
+        query: { region },
+      });
+      // Waiting cannot fix a stack built in the wrong account: it will report
+      // this same answer until the customer redeploys somewhere else.
+      if (result.reason === "wrong_account") throw new Unrecoverable(result.remediation);
+      return result.verified ? result : null;
+    });
+  } catch (err) {
+    if (!(err instanceof Unrecoverable)) throw err;
+    process.stdout.write(`${err.message}\n`);
+    return;
+  }
+
+  if (!verified) {
+    process.stdout.write("Timed out. Re-run 'preman aws' once the stack finishes.\n");
+    return;
+  }
+  connected(`AWS connected: ${verified.role_arn}`);
+
+  const groups = await callBackendJson(args, "GET", `/aws-links/${linkId}/log-groups`, {
+    token,
+    query: { region },
+  });
+  const names = (groups.log_groups || []).map((g) => g.name);
+  if (!names.length) {
+    process.stdout.write(`No log groups found in ${region}.\n`);
+    return;
+  }
+
+  process.stdout.write("\nLog groups PreMan can read:\n");
+  names.slice(0, 10).forEach((name, i) => process.stdout.write(`  ${i + 1}. ${name}\n`));
+
+  const projectId = args.value("--project-id", "");
+  if (!projectId) {
+    process.stdout.write("\nPass --project-id to start streaming one of these.\n");
+    return;
+  }
+
+  const pick = args.value("--log-group", "") || (await promptText("Stream which one? [1]: "));
+  const chosen = names.includes(pick) ? pick : names[Math.max(0, Number(pick || 1) - 1)];
+
+  const connector = await callBackendJson(args, "POST", `/projects/${projectId}/log-connectors`, {
+    token,
+    json: {
+      name: chosen,
+      connector_type: "cloudwatch",
+      stream: "backend",
+      interval_seconds: 15,
+      config: { account_link_id: linkId, region, log_group: chosen },
+    },
+  });
+  assertOk(connector, "create log connector");
+  connected(`Streaming ${chosen}. Logs appear in PreMan within about a minute.`);
+}
+
+// ---------------------------------------------------------------------------
+// GitHub
+// ---------------------------------------------------------------------------
+
+export async function githubCommand(args) {
+  const token = requireKey(args);
+
+  const before = await callBackendJson(args, "GET", "/integrations/github", { token });
+  const seen = new Set((before.integrations || before.repos || []).map((r) => r.id));
+
+  const started = await callBackendJson(args, "POST", "/integrations/github/app/install", {
+    token,
+    json: {},
+  });
+  assertOk(started, "start GitHub install");
+
+  const url = started.install_url || started.url;
+  if (!url) throw new Error("Backend returned no GitHub install URL.");
+  present(url, "install the PreMan GitHub App");
+  process.stdout.write("Pick the repositories PreMan may read.\n");
+
+  const done = await waitFor("the installation", async () => {
+    const now = await callBackendJson(args, "GET", "/integrations/github", { token });
+    const rows = now.integrations || now.repos || [];
+    // Compare against what existed before, so a user who already had repos
+    // connected is not told they are done the moment polling starts.
+    const fresh = rows.filter((r) => !seen.has(r.id));
+    return fresh.length ? fresh : null;
+  });
+
+  if (!done) {
+    process.stdout.write("Timed out. Re-run 'preman github' if the install finished.\n");
+    return;
+  }
+  connected(`GitHub connected: ${done.length} repository(ies).`);
+  for (const repo of done.slice(0, 5)) process.stdout.write(`  - ${repo.repo_url}\n`);
+}
+
+// ---------------------------------------------------------------------------
+// Slack
+// ---------------------------------------------------------------------------
+
+export async function slackCommand(args) {
+  const token = requireKey(args);
+
+  const before = await callBackendJson(args, "GET", "/slack/connections", { token });
+  const seen = new Set((before.connections || []).map((c) => c.id));
+
+  const started = await callBackendJson(args, "POST", "/slack/install", { token, json: {} });
+  assertOk(started, "start Slack install");
+
+  const url = started.install_url || started.url;
+  if (!url) throw new Error("Backend returned no Slack install URL.");
+  present(url, "add PreMan to your Slack workspace");
+
+  const done = await waitFor("the Slack install", async () => {
+    const now = await callBackendJson(args, "GET", "/slack/connections", { token });
+    const fresh = (now.connections || []).filter((c) => !seen.has(c.id));
+    return fresh.length ? fresh : null;
+  });
+
+  if (!done) {
+    process.stdout.write("Timed out. Re-run 'preman slack' if the install finished.\n");
+    return;
+  }
+  connected(`Slack connected: ${done[0].team_name || done[0].id}`);
+}
+
+// ---------------------------------------------------------------------------
+// The guided run
+// ---------------------------------------------------------------------------
+
+async function askYes(question, { assumeYes }) {
+  if (assumeYes) return true;
+  const answer = (await promptText(`${question} [Y/n]: `)).trim().toLowerCase();
+  return answer === "" || answer === "y" || answer === "yes";
+}
+
+/**
+ * Everything a new account needs, in one pass.
+ *
+ * Each step is optional and each failure is survivable: a customer who cannot
+ * finish Slack today should still leave with AWS streaming, so a step that
+ * throws is reported and the run continues rather than unwinding the ones that
+ * already worked.
+ */
+export async function onboardCommand(commandArgs, { makeArgs, authenticateTerminal, connectCommand }) {
+  const args = makeArgs(commandArgs);
+  const assumeYes = args.has("--yes");
+
+  process.stdout.write("PreMan setup\n\n");
+
+  const creds = await authenticateTerminal(args);
+  connected(`Signed in as ${creds.user_email || "your account"}.`);
+
+  const steps = [
+    {
+      name: "coding agent",
+      question: "Connect your coding agent?",
+      run: () => connectCommand([...commandArgs, "--skip-login"]),
+    },
+    { name: "GitHub", question: "Connect GitHub?", run: () => githubCommand(args) },
+    { name: "AWS logs", question: "Connect AWS?", run: () => awsCommand(args) },
+    { name: "Slack", question: "Connect Slack?", run: () => slackCommand(args) },
+  ];
+
+  const done = [];
+  const skipped = [];
+  const failed = [];
+
+  for (const step of steps) {
+    process.stdout.write(`\n── ${step.name} ──\n`);
+    if (!(await askYes(step.question, { assumeYes }))) {
+      skipped.push(step.name);
+      continue;
+    }
+    try {
+      await step.run();
+      done.push(step.name);
+    } catch (err) {
+      // Report and carry on: a failed Slack install must not cost the customer
+      // the AWS connection they just finished.
+      failed.push(`${step.name}: ${err.message}`);
+      process.stdout.write(`Could not finish ${step.name}: ${err.message}\n`);
+    }
+  }
+
+  process.stdout.write("\n── done ──\n");
+  // One line per step, marked, so the outcome is scannable rather than prose.
+  for (const name of done) process.stdout.write(`${MARK.ok()} ${name}\n`);
+  for (const name of skipped) process.stdout.write(`${MARK.skip()} ${name} (skipped)\n`);
+  for (const failure of failed) process.stdout.write(`${MARK.fail()} ${failure}\n`);
+  process.stdout.write(`\nOpen ${frontendUrl(args)} to see your logs and endpoints.\n`);
+}
+
+export const INTEGRATIONS_HELP = `
+Setup options:
+  preman onboard              Sign in, then connect agent, GitHub, AWS and Slack
+  preman aws                  Connect an AWS account and stream a log group
+  preman github               Install the PreMan GitHub App
+  preman slack                Add PreMan to a Slack workspace
+
+  --yes                       Accept every step without prompting (onboard)
+  --account <id>              AWS account id, skips the prompt
+  --region <region>           AWS region for log groups. Defaults to us-east-1
+  --project-id <id>           PreMan project to attach the log connector to
+  --log-group <name>          Log group to stream, skips the picker
+`;