not-manage 0.2.1 → 0.2.3

package/src/commands-auth.js

@@ -7,6 +7,7 @@ const {
   DEFAULT_REGION,
   REGIONS,
 } = require("./constants");
+const { AuthError, UsageError } = require("./cli-errors");
 const {
   authorizeUrl,
   deauthorize,
@@ -17,7 +18,7 @@ const {
 } = require("./clio-api");
 const { openBrowser } = require("./open-browser");
 const { waitForOAuthCallback } = require("./oauth-callback");
-const { ask, askSecret, withPrompt } = require("./prompt");
+const { ask, askSecret, bold, dim, selectOption, withPrompt } = require("./prompt");
 const {
   clearTokenSet,
   findConfig,
@@ -25,6 +26,7 @@ const {
   getTokenSet,
   normalizeRegion,
   parseRedirectUri,
+
   saveConfig,
   saveTokenSet,
 } = require("./store");
@@ -146,9 +148,11 @@ function formatConfigSummary(config) {
 
 function rewriteOAuthError(error, config) {
   const message = error && error.message ? error.message : String(error);
+  const clioErrorCode =
+    error && typeof error.clioErrorCode === "string" ? error.clioErrorCode : null;
 
-  if (message.includes("invalid_client")) {
-    return new Error(
+  if (clioErrorCode === "invalid_client" || message.includes("invalid_client")) {
+    return new AuthError(
       [
         "Clio rejected the app credentials during OAuth token exchange (`invalid_client`).",
         ...formatConfigSummary(config),
@@ -158,8 +162,12 @@ function rewriteOAuthError(error, config) {
         "- The App Key/App Secret pair does not belong to the selected Clio region.",
         "- The redirect URI registered in the Clio app does not exactly match the value above.",
         "Run `not-manage auth setup` again and copy the App Key and App Secret from the same Clio developer app.",
-        `Original error: ${message}`,
-      ].join("\n")
+        `Clio response: ${message}`,
+      ].join("\n"),
+      {
+        code: "invalid_client_credentials",
+        hint: "Run `not-manage auth setup` with the App Key and App Secret from the same Clio developer app.",
+      }
     );
   }
 
@@ -171,184 +179,354 @@ function collectSecurityWarnings(config, tokenSet) {
 }
 
 function printSetupBanner() {
-  console.log("+===========================================+");
-  console.log("|            WELCOME TO NOT MANAGE          |");
-  console.log("+===========================================+");
-  console.log("|      Local OAuth setup for this CLI       |");
-  console.log("+===========================================+");
+  console.log(bold("not-manage setup"));
+  console.log(dim("Connect not-manage to your Clio account so you can get your Clio data into an AI."));
 }
 
-function printSetupSteps() {
-  console.log("Setup flow:");
-  console.log("  [1] Choose your Clio region");
-  console.log("  [2] Open the Clio developer portal for that region and sign in");
-  console.log("  [3] Open your Clio developer app, or create one if you do not have one yet");
-  console.log("  [4] Choose the Clio Manage permissions this CLI should access");
-  console.log("  [5] Add the local callback URL to Redirect URIs, then copy the App Key and App Secret back here");
+function printSetupLinks(region, redirectUri) {
+  const regionInfo = REGIONS[region];
+  console.log(bold("Links"));
+  console.log(`  Portal     ${dim(regionInfo.developerPortalUrl)}`);
+  console.log(`  Guides     ${dim(CLIO_DEVELOPER_ACCOUNT_GUIDE_URL)}`);
+  console.log(`             ${dim(CLIO_APP_CREATION_GUIDE_URL)}`);
+  console.log(`             ${dim(CLIO_AUTHORIZATION_GUIDE_URL)}`);
+  console.log(`  Redirect   ${redirectUri}`);
 }
 
-async function maybeOpenDeveloperPortal(rl, region) {
-  const regionInfo = REGIONS[region];
-  const promptLabel = "Press Enter to open the developer portal now, or type skip to continue here";
-  const answer = String(await ask(rl, promptLabel, "")).trim().toLowerCase();
+function printPortalSteps(redirectUri) {
+  console.log(bold("In the developer portal:"));
+  console.log("  1. Open or create a Clio developer app");
+  console.log("  2. Set permissions (scopes) for this CLI");
+  console.log("  3. Add this redirect URI:");
+  console.log(`     ${bold(redirectUri)}`);
+  console.log("  4. Copy the App Key and App Secret back here");
+}
 
-  if (answer === "skip") {
-    console.log("Continuing without opening the browser.");
+function printConfidentialityNotice() {
+  console.log(dim("Output may contain confidential client data."));
+  console.log(dim("Redaction (--redacted) is best-effort. Review all output before sharing."));
+}
+
+function printSetupIntro() {
+  printSetupBanner();
+  console.log("");
+  printConfidentialityNotice();
+}
+
+function normalizeOptionalText(value) {
+  if (value === undefined || value === null) {
+    return undefined;
+  }
+
+  const text = String(value).trim();
+  return text || undefined;
+}
+
+function buildAuthSetupUsage() {
+  return [
+    "Usage: not-manage auth setup --confirm-confidentiality --client-id <value> --client-secret <value> [--region <code>] [--redirect-uri <url>] [--open-browser true|false]",
+    "Run `not-manage auth setup --help` for command details.",
+  ].join("\n");
+}
+
+function requireInteractiveSetupFlag(flagName, details) {
+  const prefix = `\`${flagName}\` is required outside an interactive terminal.`;
+  return new UsageError(details ? `${prefix}\n${details}` : prefix, {
+    code: "missing_interactive_setup_flag",
+    hint: "not-manage auth setup --help",
+    details: { missing_flags: [flagName] },
+  });
+}
+
+function buildRegionOptions() {
+  return Object.values(REGIONS).map((region) => ({
+    label: `${region.code} - ${region.label} ${dim(`(${region.host})`)}`,
+    value: region.code,
+  }));
+}
+
+function normalizeSetupOptions(options = {}) {
+  const region = normalizeOptionalText(options.region);
+  const redirectUri = normalizeOptionalText(options.redirectUri);
+
+  return {
+    clientId: normalizeOptionalText(options.clientId),
+    clientSecret: normalizeOptionalText(options.clientSecret),
+    confirmConfidentiality: options.confirmConfidentiality === true,
+    noInput: options.noInput === true,
+    openBrowser: typeof options.openBrowser === "boolean" ? options.openBrowser : undefined,
+    redirectUri: redirectUri ? parseRedirectUri(redirectUri) : DEFAULT_REDIRECT_URI,
+    region: region ? normalizeRegion(region) : undefined,
+  };
+}
+
+function buildMissingSetupOptionsError(missingFlags) {
+  return new UsageError(
+    [
+      `Missing required setup options: ${missingFlags.join(", ")}.`,
+      buildAuthSetupUsage(),
+    ].join("\n"),
+    {
+      code: "missing_setup_options",
+      hint: "not-manage auth setup --help",
+      details: { missing_flags: missingFlags },
+    }
+  );
+}
+
+function buildMissingRevokeConfirmationError() {
+  return new UsageError(
+    [
+      "`not-manage auth revoke` needs confirmation before it clears tokens.",
+      "Re-run with `--yes` to perform the revoke, or `--dry-run` to inspect what would happen.",
+    ].join("\n"),
+    {
+      code: "confirmation_required",
+      hint: "not-manage auth revoke --dry-run",
+    }
+  );
+}
+
+function buildEmptySetupValueError(label, flagName) {
+  return new UsageError(`${label} is required.`, {
+    code: "missing_setup_options",
+    hint: "not-manage auth setup --help",
+    details: { missing_flags: [flagName] },
+  });
+}
+
+function sameSavedConfig(existingConfig, configInput) {
+  return Boolean(
+    existingConfig &&
+      existingConfig.region === configInput.region &&
+      existingConfig.clientId === configInput.clientId &&
+      existingConfig.clientSecret === configInput.clientSecret &&
+      existingConfig.redirectUri === configInput.redirectUri
+  );
+}
+
+async function ensureConfidentialityNoticeAcknowledged(rl, options) {
+  if (options.confirmConfidentiality) {
     return;
   }
 
-  try {
-    await openBrowser(regionInfo.developerPortalUrl);
-    console.log(`Opened the ${regionInfo.label} Clio developer portal in your browser.`);
-  } catch (_error) {
-    console.log("Could not open the Clio developer portal automatically.");
-    console.log(`Open this URL manually: ${regionInfo.developerPortalUrl}`);
+  if (!rl) {
+    throw requireInteractiveSetupFlag("--confirm-confidentiality", buildAuthSetupUsage());
   }
-}
 
-function printSetupLinks(region, redirectUri) {
-  const regionInfo = REGIONS[region];
-  console.log("Clio setup links:");
-  console.log(`- Developer portal: ${regionInfo.developerPortalUrl}`);
-  console.log(`- Developer account guide: ${CLIO_DEVELOPER_ACCOUNT_GUIDE_URL}`);
-  console.log(`- App creation guide: ${CLIO_APP_CREATION_GUIDE_URL}`);
-  console.log(`- Authorization guide: ${CLIO_AUTHORIZATION_GUIDE_URL}`);
-  console.log(`- Add this redirect URI in your Clio app: ${redirectUri}`);
+  await confirmConfidentialityNotice(rl);
 }
 
-function printClioAppFieldGuide(redirectUri) {
-  console.log("Clio app form guide:");
-  console.log("");
-  console.log("  Required:");
-  console.log("  - Website URL: use your firm website, company site, or GitHub repo.");
-  console.log("  - Do not put the local callback URL in Website URL.");
-  console.log("  - Clio Manage permissions / scopes: select only the permissions this CLI will actually use.");
-  console.log("  - Redirect URIs: copy this exact URL on its own line:");
-  console.log(`    ${redirectUri}`);
-  console.log("");
-  console.log("  Optional:");
-  console.log("  - Support URL and Deauthorization callback URL can stay blank unless you already use them.");
+async function resolveSetupClientId(rl, options) {
+  if (options.clientId) {
+    return options.clientId;
+  }
+
+  if (!rl) {
+    throw buildMissingSetupOptionsError(["--client-id"]);
+  }
+
+  const clientId = normalizeOptionalText(await ask(rl, "App Key / Client ID"));
+  if (!clientId) {
+    throw buildEmptySetupValueError("App Key / Client ID", "--client-id");
+  }
+
+  return clientId;
 }
 
-function printDeveloperPortalReminder(redirectUri) {
-  console.log("In the developer portal:");
-  console.log("");
-  console.log("  First:");
-  console.log("  - Sign in, then open the Clio developer app you want this CLI to use.");
-  console.log("  - Use an existing app in this region, or create a new one.");
-  console.log("");
-  console.log("  Permissions:");
-  console.log("  - Select only the Clio Manage permissions (OAuth scopes) this CLI should access.");
-  console.log("");
-  console.log("  Redirect URI:");
-  console.log("  - Register this exact URL in your Clio developer app:");
-  console.log(`    ${redirectUri}`);
-  console.log("");
-  console.log("  Then:");
-  console.log("  - Copy the App Key and App Secret from that same app back here.");
+async function resolveSetupClientSecret(rl, options) {
+  if (options.clientSecret) {
+    return options.clientSecret;
+  }
+
+  if (!rl) {
+    throw buildMissingSetupOptionsError(["--client-secret"]);
+  }
+
+  const clientSecret = normalizeOptionalText(await askSecret(rl, "App Secret / Client Secret"));
+  if (!clientSecret) {
+    throw buildEmptySetupValueError("App Secret / Client Secret", "--client-secret");
+  }
+
+  return clientSecret;
 }
 
-function printConfidentialityNotice() {
-  console.log("Confidentiality notice:");
-  console.log("  not-manage can display client-identifying, confidential, or privileged matter data.");
-  console.log("  `--redacted` is best-effort only and may miss identifiers in labels, custom fields, or free text.");
-  console.log("  Review all output before sharing it with AI tools, tickets, chats, or other third parties.");
-  console.log("  Use only with workflows and vendors your firm has approved.");
+async function resolveSetupRegion(rl, options) {
+  if (options.region) {
+    return options.region;
+  }
+
+  if (!rl) {
+    return DEFAULT_REGION;
+  }
+
+  console.log(dim("Choose a region by number or code."));
+  const regionOptions = buildRegionOptions();
+  return selectOption(
+    rl,
+    "Region",
+    regionOptions,
+    regionOptions.findIndex((option) => option.value === DEFAULT_REGION)
+  );
 }
 
-function printSetupIntro(redirectUri) {
-  printSetupBanner();
-  console.log("");
-  console.log("This setup is for developers who are connecting the CLI to their own Clio app.");
-  console.log("If this is your first time doing that, this guide will walk you through it.");
-  console.log("");
-  printConfidentialityNotice();
-  console.log("");
-  printSetupSteps();
-  console.log("");
-  console.log("Useful links:");
-  console.log(`- Developer account guide: ${CLIO_DEVELOPER_ACCOUNT_GUIDE_URL}`);
-  console.log(`- App creation guide: ${CLIO_APP_CREATION_GUIDE_URL}`);
-  console.log(`- OAuth guide: ${CLIO_AUTHORIZATION_GUIDE_URL}`);
-  console.log("");
-  printClioAppFieldGuide(redirectUri);
-  console.log("");
-  console.log("You do not need to paste the redirect URI back into this CLI unless you want to override it.");
-  console.log("");
-  console.log("Region options:");
-  Object.values(REGIONS).forEach((region) => {
-    console.log(`- ${region.code}: ${region.label} (${region.host})`);
+async function maybePromptRevokeConfirmation() {
+  if (!process.stdin.isTTY || !process.stdout.isTTY) {
+    throw buildMissingRevokeConfirmationError();
+  }
+
+  return withPrompt(async (rl) => {
+    const answer = String(await ask(rl, "Type revoke to continue, or press Enter to cancel", ""))
+      .trim()
+      .toLowerCase();
+
+    if (answer !== "revoke") {
+      console.log("Revoke cancelled.");
+      return false;
+    }
+
+    return true;
   });
 }
 
+async function maybeOpenDeveloperPortal(rl, region, openBrowserPreference) {
+  if (openBrowserPreference === false) {
+    console.log("Continuing without opening the browser.");
+    return;
+  }
+
+  if (openBrowserPreference === undefined) {
+    if (!rl) {
+      return;
+    }
+
+    const promptLabel = "Press Enter to open the developer portal, or type skip";
+    const answer = String(await ask(rl, promptLabel, "")).trim().toLowerCase();
+
+    if (answer === "skip") {
+      console.log("Continuing without opening the browser.");
+      return;
+    }
+  }
+
+  const regionInfo = REGIONS[region];
+
+  try {
+    await openBrowser(regionInfo.developerPortalUrl);
+    console.log(`Opened ${regionInfo.label} developer portal in your browser.`);
+  } catch (_error) {
+    console.log("Could not open browser automatically.");
+    console.log(`Open this URL manually: ${regionInfo.developerPortalUrl}`);
+  }
+}
+
 async function confirmConfidentialityNotice(rl) {
   const answer = String(
     await ask(
       rl,
-      "Type yes to confirm you will review output before sharing it outside your firm"
+      "Press Enter to confirm, or type no to abort"
     )
   )
     .trim()
     .toLowerCase();
 
-  if (answer !== "yes") {
-    throw new Error(
-      "Setup aborted. Review your confidentiality and client-sharing requirements, then rerun `not-manage auth setup`."
+  if (answer === "no") {
+    throw new UsageError(
+      "Setup aborted. Review your confidentiality and client-sharing requirements, then rerun `not-manage auth setup`.",
+      {
+        code: "setup_aborted",
+        hint: "not-manage auth setup --help",
+      }
     );
   }
 }
 
 async function authSetup(options = {}) {
-  printSetupIntro(DEFAULT_REDIRECT_URI);
+  printSetupIntro();
   console.log("");
 
-  const configInput = await withPrompt(async (rl) => {
-    await confirmConfidentialityNotice(rl);
-    const regionRaw = await ask(rl, "Region", DEFAULT_REGION);
-    const region = normalizeRegion(regionRaw);
-    const regionInfo = REGIONS[region];
-
-    console.log(`Using ${regionInfo.label} (${regionInfo.host}).`);
-    console.log(`Developer portal: ${regionInfo.developerPortalUrl}`);
-    console.log("If you already have a Clio developer app in this region, you can use it.");
-    console.log("If not, create one there first, then come back here.");
-    await maybeOpenDeveloperPortal(rl, region);
-    printDeveloperPortalReminder(DEFAULT_REDIRECT_URI);
-
-    const clientId = await ask(rl, "App Key / Client ID (from your Clio developer app)");
-    if (!clientId) {
-      throw new Error("App Key / Client ID is required.");
-    }
-
-    const clientSecret = await askSecret(
-      rl,
-      "App Secret / Client Secret (from the same Clio app)"
-    );
-    if (!clientSecret) {
-      throw new Error("App Secret / Client Secret is required.");
-    }
-
-    const redirectUriOverride = await ask(
-      rl,
-      "Custom redirect URI override (optional; press Enter to keep the default)"
-    );
-    const redirectUri = parseRedirectUri(redirectUriOverride || DEFAULT_REDIRECT_URI);
-    return {
-      region,
-      clientId,
-      clientSecret,
-      redirectUri,
-    };
-  });
-
+  const normalizedOptions = normalizeSetupOptions(options);
+  const needsPrompt =
+    !normalizedOptions.confirmConfidentiality ||
+    !normalizedOptions.clientId ||
+    !normalizedOptions.clientSecret;
+
+  const configInput = await (needsPrompt &&
+    !normalizedOptions.noInput &&
+    process.stdin.isTTY &&
+    process.stdout.isTTY
+    ? withPrompt(async (rl) => {
+        await ensureConfidentialityNoticeAcknowledged(rl, normalizedOptions);
+
+        console.log("");
+        const region = await resolveSetupRegion(rl, normalizedOptions);
+        const regionInfo = REGIONS[region];
+
+        console.log("");
+        printPortalSteps(normalizedOptions.redirectUri);
+        console.log("");
+        await maybeOpenDeveloperPortal(rl, region, normalizedOptions.openBrowser);
+
+        console.log("");
+        console.log(dim(`Using ${regionInfo.label} (${regionInfo.host}).`));
+
+        const clientId = await resolveSetupClientId(rl, normalizedOptions);
+        const clientSecret = await resolveSetupClientSecret(rl, normalizedOptions);
+
+        return {
+          region,
+          clientId,
+          clientSecret,
+          redirectUri: normalizedOptions.redirectUri,
+        };
+      })
+    : (async () => {
+        await ensureConfidentialityNoticeAcknowledged(null, normalizedOptions);
+
+        const missingFlags = [];
+        if (!normalizedOptions.clientId) {
+          missingFlags.push("--client-id");
+        }
+        if (!normalizedOptions.clientSecret) {
+          missingFlags.push("--client-secret");
+        }
+        if (missingFlags.length > 0) {
+          throw buildMissingSetupOptionsError(missingFlags);
+        }
+
+        const region = normalizedOptions.region || DEFAULT_REGION;
+        const regionInfo = REGIONS[region];
+
+        printPortalSteps(normalizedOptions.redirectUri);
+        console.log("");
+        await maybeOpenDeveloperPortal(null, region, normalizedOptions.openBrowser);
+
+        console.log("");
+        console.log(dim(`Using ${regionInfo.label} (${regionInfo.host}).`));
+
+        return {
+          region,
+          clientId: normalizedOptions.clientId,
+          clientSecret: normalizedOptions.clientSecret,
+          redirectUri: normalizedOptions.redirectUri,
+        };
+      })());
+
+  const existingConfig = await findConfig();
+  const configChanged = !sameSavedConfig(existingConfig, configInput);
   const saved = await saveConfig(configInput);
-  await clearTokenSet();
+  if (configChanged) {
+    await clearTokenSet();
+  }
 
   console.log("");
-  console.log("Saved credentials to secure keychain.");
-  console.log(`Region: ${saved.region} (${REGIONS[saved.region].label})`);
+  console.log(bold("Your credentials have been securely saved on your local machine in the keychain."));
+  if (!configChanged) {
+    console.log(dim("Existing OAuth token preserved because the saved app credentials did not change."));
+  }
+  console.log(dim(`Region: ${saved.region} (${REGIONS[saved.region].label})`));
+  console.log("");
   printSetupLinks(saved.region, saved.redirectUri);
-  printClioAppFieldGuide(saved.redirectUri);
 
   if (!options.skipNextStepHint) {
     console.log("");
@@ -446,8 +624,7 @@ async function authStatus(options = {}) {
   });
 }
 
-async function authRevoke() {
-  const config = await getConfig();
+async function authRevoke(options = {}) {
   const tokenSet = await getTokenSet();
 
   if (!tokenSet || !tokenSet.accessToken) {
@@ -455,6 +632,18 @@ async function authRevoke() {
     return;
   }
 
+  if (options.dryRun) {
+    console.log("Dry run: would revoke the current token in Clio and clear the local keychain token.");
+    return;
+  }
+
+  const confirmed = options.yes === true ? true : await maybePromptRevokeConfirmation();
+  if (!confirmed) {
+    return;
+  }
+
+  const config = await getConfig();
+
   try {
     const accessToken = await getValidAccessToken(config, tokenSet);
     await deauthorize(config, accessToken);
@@ -484,8 +673,8 @@ async function whoAmI(options = {}) {
   console.log(`ID: ${user.id}`);
 }
 
-async function setupWizard() {
-  const config = await authSetup({ skipNextStepHint: true });
+async function setupWizard(options = {}) {
+  const config = await authSetup({ ...options, skipNextStepHint: true });
   console.log("");
   console.log("Continuing with OAuth login...");
   await authLogin({ config });
@@ -501,8 +690,7 @@ async function maybeRunSetupOnFirstUse() {
     return false;
   }
 
-  console.log("No Clio app credentials are configured yet.");
-  console.log("Starting guided setup...");
+  console.log("No credentials found. Starting setup...");
   console.log("");
   await setupWizard();
   return true;