premanmcp 0.15.3 → 0.16.1

package/bin/integrations.js

@@ -366,6 +366,145 @@ export async function slackCommand(args) {
 // The guided run
 // ---------------------------------------------------------------------------
 
+/**
+ * Ask, once, before PreMan writes into an SDK repository or a docs site.
+ *
+ * Two questions rather than one. Agreeing to a generated client library is not
+ * agreeing to have your documentation site rewritten (a docs release replaces
+ * mkdocs.yml), and a single answer used to buy both.
+ *
+ * Says nothing when there is nothing to ask: no connected repository, no
+ * detected target, or an answer already on file. A walk that re-asks a question
+ * it has already had answered teaches people that answering buys them nothing,
+ * which is the whole reason this moved out of the delivery run.
+ */
+async function offerReleaseTargets(args, checkout, { assumeYes }) {
+  // SILENT is a step that did not happen rather than one that was skipped: no
+  // heading, and no line in the summary either. A repository with no SDK and no
+  // docs site has nothing to decide here, and saying so is worse than saying
+  // nothing.
+  const SILENT = { state: "skipped", silent: true };
+
+  const integrationId = checkout?.match?.integration_id;
+  if (!integrationId) return SILENT;
+
+  const token = resolveApiKey(args);
+  const path = `/sdk/integrations/${integrationId}/distribution`;
+  let detected = null;
+  try {
+    detected = await callBackendJson(args, "GET", path, { token });
+  } catch {
+    // Detection costs one root listing per repository in the installation. It
+    // is the least important thing in this walk and never worth failing setup
+    // over.
+    return SILENT;
+  }
+
+  const sdkRepo = detected?.sdk_repo || "";
+  const docsRepo = detected?.docs_repo || "";
+  if (!sdkRepo && !docsRepo) return SILENT;
+
+  banner("Releases");
+  if (detected?.confirmed) {
+    process.stdout.write(`${MARK.ok()} Release targets already answered.\n`);
+    return;
+  }
+
+  const body = {};
+  const decided = [];
+  for (const [repo, field, flag, question] of [
+    [
+      sdkRepo,
+      "sdk_repo",
+      "publish_sdk",
+      `${sdkRepo} looks like your client library. Open pull requests there with generated SDKs?`,
+    ],
+    [
+      docsRepo,
+      "docs_repo",
+      "publish_docs",
+      // The wider blast radius is named in the question, because it is the part
+      // somebody would resent discovering afterwards.
+      `${docsRepo} looks like your docs site. Open pull requests there? Releases rewrite mkdocs.yml.`,
+    ],
+  ]) {
+    if (!repo) continue;
+    const answer = await askRelease(question, assumeYes);
+    if (answer === null) continue;
+    body[field] = repo;
+    body[flag] = answer;
+    decided.push([repo, answer]);
+  }
+  if (!decided.length) return { state: "skipped" };
+
+  await callBackendJson(args, "PUT", path, { token, json: body });
+
+  for (const [repo, allowed] of decided) {
+    // A no is reported as recorded, not as a step that failed. It is an answer,
+    // and PreMan will not come back to it.
+    if (allowed) process.stdout.write(`${MARK.ok()} Publishing to ${repo}.\n`);
+    else
+      process.stdout.write(
+        `${MARK.skip()} Not publishing to ${repo}. PreMan will not ask again.\n`
+      );
+  }
+}
+
+/**
+ * Yes, no, or nobody answered.
+ *
+ * Three outcomes rather than two, and the third is the whole reason this does
+ * not use `confirm`. That helper reads a closed stdin as a no, which is right
+ * for a step that then simply does less work. A no here is *recorded*, and a
+ * recorded no is never asked again, so reading silence as refusal would retire
+ * a question the customer never saw.
+ *
+ * The same argument applies to --yes: accepting defaults on someone's behalf is
+ * fine for a hook or a download, and is not a way to acquire write access to a
+ * repository nobody mentioned. So an unattended run leaves both questions open.
+ *
+ * The default is no, for the reason silence means no everywhere else PreMan
+ * writes to somebody's repository.
+ */
+async function askRelease(question, assumeYes) {
+  if (assumeYes) return null;
+  const answer = (await promptText(`${question} [y/N]: `)).trim().toLowerCase();
+  if (answer === "") return null;
+  return answer === "y" || answer === "yes";
+}
+
+/**
+ * Put PreMan on screen, signed in as the account this walk just used.
+ *
+ * Returns whether the app is actually up, because that is what decides the last
+ * line of the walk and nothing downstream can work it out.
+ */
+async function showDesktopSignedIn(openDesktopSignedIn, args, creds, stopOpening) {
+  // The same --dest the install honoured, or the launch would look for the app
+  // somewhere it was never copied to.
+  const destination = args.value("--dest", "/Applications");
+  const opened = await openDesktopSignedIn(creds, { destination });
+  stopOpening?.();
+  if (opened.state === "opened-signed-in") {
+    process.stdout.write("Opened PreMan, signed in as this account.\n");
+  } else if (opened.state === "not-installed") {
+    process.stdout.write(
+      `PreMan is not in ${destination} yet \u2014 open it once installed and sign in.\n`
+    );
+  } else {
+    // Either the session could not be handed over or this app is too old to take
+    // it up. Say so rather than let the customer wonder why they are looking at
+    // a login screen.
+    process.stdout.write("Opened PreMan \u2014 sign in with the account you just used.\n");
+  }
+  return opened.state !== "not-installed";
+}
+
+/** One step heading, in the one format the whole walk uses. */
+function banner(name) {
+  process.stdout.write(`\n── ${name} ──\n`);
+}
+
 /**
  * "yes" | "no" | "back" -- back only offered once there is somewhere to go.
  *
@@ -499,6 +638,22 @@ export async function onboardCommand(
         process.stdout.write(
           `${checkout.slug} is still not shared. Add it at ${INSTALLATIONS_URL}.\n`
         );
+        // Nothing was connected, so this step did not finish. Returning nothing
+        // marks it done, which is how the walk came to print a tick directly
+        // under a line saying the repository is not shared — and why somebody
+        // would then open the app expecting to find GitHub set up and find
+        // "Continue with GitHub" instead. The sibling branch below already
+        // reports this correctly; this one simply never did.
+        return { state: "skipped" };
+      },
+      onSkip: () => {
+        // The one question in this walk that decides whether a fix from this
+        // code can ever land anywhere. Declining it in silence is how the gap
+        // stays invisible until a fix task finishes and produces nothing.
+        process.stdout.write(
+          `${MARK.skip()} ${checkout.slug} stays disconnected — fixes here cannot open pull requests.\n`
+        );
+        process.stdout.write(`  Run '${cliInvocation()} github' here to change that.\n`);
       },
     });
   } else {
@@ -525,6 +680,19 @@ export async function onboardCommand(
     });
   }
 
+  // The only questions in this walk about repositories *other* than the one
+  // being connected. They are asked here, while PreMan has just read the
+  // installation and can name what it found, rather than weeks later from
+  // inside a delivery run, on a screen most people never opened.
+  steps.push({
+    name: "Releases",
+    // Prints its own heading, and only once it knows there is a question. A
+    // walk that draws an empty section has told the customer something is
+    // missing when nothing is.
+    ownBanner: true,
+    run: () => offerReleaseTargets(args, checkout, { assumeYes }),
+  });
+
   steps.push({
     name: "Push checks",
     question: "Check your endpoints on every git push in this repo?",
@@ -569,8 +737,21 @@ export async function onboardCommand(
   if (desktop?.state === "installed") {
     steps.push({
       name: "Desktop app",
-      run: () => {
+      // Nothing to download, which is the point of this branch. It is not a
+      // reason to stop at the sentence: the step exists to leave the customer
+      // looking at PreMan, so the one run with nothing to install was also the
+      // only run that opened nothing, and it closed by sending someone to a
+      // website instead of the app already sitting on their machine.
+      run: async () => {
         process.stdout.write(`${MARK.ok()} PreMan desktop app already installed.\n`);
+        const stopOpening = showOpeningDesktop();
+        try {
+          return {
+            appOpened: await showDesktopSignedIn(openDesktopSignedIn, args, creds, stopOpening),
+          };
+        } finally {
+          stopOpening();
+        }
       },
     });
   } else if (!desktop) {
@@ -598,26 +779,15 @@ export async function onboardCommand(
                 return installed;
               }
               stopOpening ??= showOpeningDesktop();
-              // The same --dest the install honoured, or the launch would look
-              // for the app somewhere it was never copied to.
-              const destination = args.value("--dest", "/Applications");
-              const opened = await openDesktopSignedIn(creds, { destination });
-              stopOpening();
-              if (opened.state === "opened-signed-in") {
-                process.stdout.write("Opened PreMan, signed in as this account.\n");
-              } else if (opened.state === "not-installed") {
-                process.stdout.write(
-                  `PreMan is not in ${destination} yet \u2014 open it once installed and sign in.\n`
-                );
-              } else {
-                // Either the session could not be handed over or this app is too
-                // old to take it up. Say so rather than let the customer wonder
-                // why they are looking at a login screen.
-                process.stdout.write("Opened PreMan \u2014 sign in with the account you just used.\n");
-              }
-              // Whether the app is on screen decides what the last line of the walk
-              // should say, and only this closure knows.
-              return { ...installed, appOpened: opened.state !== "not-installed" };
+              return {
+                ...installed,
+                appOpened: await showDesktopSignedIn(
+                  openDesktopSignedIn,
+                  args,
+                  creds,
+                  stopOpening
+                ),
+              };
             } finally {
               stopOpening?.();
             }
@@ -636,7 +806,7 @@ export async function onboardCommand(
   let i = 0;
   while (i < steps.length) {
     const step = steps[i];
-    process.stdout.write(`\n── ${step.name} ──\n`);
+    if (!step.ownBanner) banner(step.name);
 
     if (step.question) {
       // "back" goes to the last step that asked something, not simply to the
@@ -675,6 +845,13 @@ export async function onboardCommand(
       // at the end of a successful install: the install reports state "installed",
       // which is none of the three, so it printed as a failure with no detail.
       const reported = await step.run();
+      // A step that never announced itself does not belong in the summary
+      // either: a line reading "(skipped)" for work nobody was offered reads as
+      // something having gone wrong.
+      if (reported?.silent) {
+        i += 1;
+        continue;
+      }
       const state =
         { failed: "failed", skipped: "skipped", unsupported: "skipped" }[reported?.state] ||
         "done";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "premanmcp",
-  "version": "0.15.3",
+  "version": "0.16.1",
   "description": "Turn APIs into agent-callable MCP tools with auth, testing, and audit logs",
   "type": "module",
   "bin": {