not-manage 0.1.17

package/src/commands-users.js

@@ -0,0 +1,192 @@
+const {
+  fetchUser,
+  fetchUsersPage,
+  getValidAccessToken,
+} = require("./clio-api");
+const { getConfig, getTokenSet } = require("./store");
+const {
+  clip,
+  compactQuery,
+  fetchPages,
+  formatBoolean,
+  parseLimit,
+  printKeyValueRows,
+  readUserName,
+} = require("./resource-utils");
+const { maybeRedactData, maybeRedactPayload } = require("./redaction");
+
+const DEFAULT_LIST_FIELDS =
+  "id,name,first_name,last_name,email,enabled,roles,subscription_type,phone_number,time_zone,rate,account_owner,clio_connect,court_rules_default_attendee,created_at,updated_at";
+const DEFAULT_GET_FIELDS =
+  "id,name,first_name,last_name,email,enabled,roles,subscription_type,phone_number,time_zone,rate,account_owner,clio_connect,court_rules_default_attendee,created_at,updated_at";
+
+function readRoleList(user) {
+  const roles = Array.isArray(user?.roles) ? user.roles : [];
+  if (roles.length === 0) {
+    return "-";
+  }
+  return roles.join(", ");
+}
+
+function buildUserQuery(options) {
+  return compactQuery({
+    created_since: options.createdSince || undefined,
+    enabled:
+      options.enabled === undefined || options.enabled === null
+        ? undefined
+        : Boolean(options.enabled),
+    fields: options.fields || DEFAULT_LIST_FIELDS,
+    include_co_counsel: options.includeCoCounsel ? true : undefined,
+    limit: parseLimit(options.limit, 2000),
+    name: options.name || undefined,
+    order: options.order || undefined,
+    page_token: options.pageToken || undefined,
+    pending_setup:
+      options.pendingSetup === undefined || options.pendingSetup === null
+        ? undefined
+        : Boolean(options.pendingSetup),
+    role: options.role || undefined,
+    subscription_type: options.subscriptionType || undefined,
+    updated_since: options.updatedSince || undefined,
+  });
+}
+
+function formatUserRow(user) {
+  return {
+    id: String(user.id || "-"),
+    name: readUserName(user),
+    email: String(user.email || "-"),
+    enabled: formatBoolean(user.enabled),
+    roles: readRoleList(user),
+  };
+}
+
+function printUserList(rows, options) {
+  if (rows.length === 0) {
+    console.log("No users found for the selected filters.");
+    return;
+  }
+
+  const visibleRows = rows.slice(0, 50);
+  console.log("ID       NAME                         EMAIL                        ENABLED ROLES");
+  console.log("-------- ---------------------------- ---------------------------- ------- ------------------------------");
+
+  visibleRows.forEach((row) => {
+    const line = [
+      clip(row.id, 8).padEnd(8, " "),
+      clip(row.name, 28).padEnd(28, " "),
+      clip(row.email, 28).padEnd(28, " "),
+      clip(row.enabled, 7).padEnd(7, " "),
+      clip(row.roles, 30),
+    ].join(" ");
+
+    console.log(line);
+  });
+
+  if (rows.length > visibleRows.length) {
+    console.log(`Showing ${visibleRows.length} of ${rows.length} users. Use --json for full output.`);
+  }
+
+  if (!options.all && options.nextPageUrl) {
+    console.log("");
+    console.log("More results are available.");
+    console.log("Run again with `--all` or pass `--page-token` from `--json` output.");
+  }
+}
+
+function printUser(user) {
+  printKeyValueRows([
+    ["ID", user.id],
+    ["Name", readUserName(user)],
+    ["Email", user.email],
+    ["Enabled", formatBoolean(user.enabled)],
+    ["Roles", readRoleList(user)],
+    ["Subscription", user.subscription_type],
+    ["Phone", user.phone_number],
+    ["Time Zone", user.time_zone],
+    ["Rate", user.rate],
+    ["Account Owner", formatBoolean(user.account_owner)],
+    ["Clio Connect", formatBoolean(user.clio_connect)],
+    ["Court Rules Default Attendee", formatBoolean(user.court_rules_default_attendee)],
+    ["Created", user.created_at],
+    ["Updated", user.updated_at],
+  ]);
+}
+
+async function getAuthContext() {
+  const config = await getConfig();
+  const tokenSet = await getTokenSet();
+  const accessToken = await getValidAccessToken(config, tokenSet);
+  return { config, accessToken };
+}
+
+async function usersList(options = {}) {
+  const query = buildUserQuery(options);
+  const { config, accessToken } = await getAuthContext();
+  const result = await fetchPages(
+    (pageQuery, nextPageUrl) => fetchUsersPage(config, accessToken, pageQuery, nextPageUrl),
+    query,
+    Boolean(options.all)
+  );
+
+  if (options.json) {
+    const firstPage = maybeRedactPayload(result.firstPage, options, "user");
+    if (!options.all) {
+      console.log(JSON.stringify(firstPage, null, 2));
+      return;
+    }
+
+    const data = maybeRedactData(result.data, options, "user");
+    console.log(
+      JSON.stringify(
+        {
+          data,
+          meta: {
+            pages_fetched: result.pagesFetched,
+            returned_count: data.length,
+          },
+        },
+        null,
+        2
+      )
+    );
+    return;
+  }
+
+  const rows = maybeRedactData(result.data, options, "user").map(formatUserRow);
+  printUserList(rows, { all: Boolean(options.all), nextPageUrl: result.nextPageUrl });
+  console.log("");
+  console.log(
+    `Returned ${rows.length} user${rows.length === 1 ? "" : "s"} across ${result.pagesFetched} page${result.pagesFetched === 1 ? "" : "s"}.`
+  );
+}
+
+async function usersGet(options = {}) {
+  if (!options.id) {
+    throw new Error("Usage: not-manage users get <id> [--fields ...] [--json]");
+  }
+
+  const { config, accessToken } = await getAuthContext();
+  const payload = await fetchUser(config, accessToken, options.id, {
+    fields: options.fields || DEFAULT_GET_FIELDS,
+  });
+  const redactedPayload = maybeRedactPayload(payload, options, "user");
+
+  if (options.json) {
+    console.log(JSON.stringify(redactedPayload, null, 2));
+    return;
+  }
+
+  printUser(redactedPayload?.data || {});
+}
+
+module.exports = {
+  usersGet,
+  usersList,
+  __private: {
+    buildUserQuery,
+    formatUserRow,
+    printUser,
+    printUserList,
+  },
+};

package/src/constants.js

@@ -0,0 +1,50 @@
+const SERVICE_NAME = "com.notoperations.not-manage-cli";
+const LEGACY_SERVICE_NAME = "com.notoperations.clio-manage-cli";
+const DEFAULT_REGION = "us";
+const DEFAULT_REDIRECT_URI = "http://127.0.0.1:53123/callback";
+const OAUTH_TIMEOUT_MS = 5 * 60 * 1000;
+const CLIO_APP_CREATION_GUIDE_URL =
+  "https://docs.developers.clio.com/api-docs/clio-manage/applications/";
+const CLIO_AUTHORIZATION_GUIDE_URL =
+  "https://docs.developers.clio.com/api-docs/clio-manage/authorization/";
+const CLIO_DEVELOPER_ACCOUNT_GUIDE_URL =
+  "https://docs.developers.clio.com/handbook/getting-started/get-a-developer-account/";
+
+const REGIONS = {
+  us: {
+    code: "us",
+    label: "United States",
+    developerPortalUrl: "https://developers.clio.com",
+    host: "app.clio.com",
+  },
+  ca: {
+    code: "ca",
+    label: "Canada",
+    developerPortalUrl: "https://ca.developers.clio.com",
+    host: "ca.app.clio.com",
+  },
+  eu: {
+    code: "eu",
+    label: "Europe",
+    developerPortalUrl: "https://eu.developers.clio.com",
+    host: "eu.app.clio.com",
+  },
+  au: {
+    code: "au",
+    label: "Australia",
+    developerPortalUrl: "https://au.developers.clio.com",
+    host: "au.app.clio.com",
+  },
+};
+
+module.exports = {
+  SERVICE_NAME,
+  LEGACY_SERVICE_NAME,
+  DEFAULT_REGION,
+  DEFAULT_REDIRECT_URI,
+  OAUTH_TIMEOUT_MS,
+  CLIO_APP_CREATION_GUIDE_URL,
+  CLIO_AUTHORIZATION_GUIDE_URL,
+  CLIO_DEVELOPER_ACCOUNT_GUIDE_URL,
+  REGIONS,
+};

package/src/keychain.js

@@ -0,0 +1,63 @@
+const { LEGACY_SERVICE_NAME, SERVICE_NAME } = require("./constants");
+
+function loadKeytar() {
+  try {
+    return require("keytar");
+  } catch (error) {
+    throw new Error(
+      "Secure keychain is unavailable. Install dependencies with `npm install` and ensure your OS keychain is enabled."
+    );
+  }
+}
+
+function normalizeKeychainError(action, error) {
+  const rawMessage = error && error.message ? error.message : String(error || "");
+  const message = rawMessage && rawMessage !== "[object Object]" ? rawMessage : "unknown error";
+  return new Error(
+    `OS keychain ${action} failed (${message}). This CLI requires a working OS keychain.`
+  );
+}
+
+async function setSecret(account, value) {
+  try {
+    const keytar = loadKeytar();
+    await keytar.setPassword(SERVICE_NAME, account, value);
+  } catch (error) {
+    throw normalizeKeychainError("write", error);
+  }
+}
+
+async function getSecret(account) {
+  try {
+    const keytar = loadKeytar();
+    // Read the renamed service first, then fall back to the legacy one.
+    for (const serviceName of [SERVICE_NAME, LEGACY_SERVICE_NAME]) {
+      const value = await keytar.getPassword(serviceName, account);
+      if (value) {
+        return value;
+      }
+    }
+    return null;
+  } catch (error) {
+    throw normalizeKeychainError("read", error);
+  }
+}
+
+async function deleteSecret(account) {
+  try {
+    const keytar = loadKeytar();
+    await Promise.all(
+      [SERVICE_NAME, LEGACY_SERVICE_NAME].map((serviceName) =>
+        keytar.deletePassword(serviceName, account)
+      )
+    );
+  } catch (error) {
+    throw normalizeKeychainError("delete", error);
+  }
+}
+
+module.exports = {
+  setSecret,
+  getSecret,
+  deleteSecret,
+};

package/src/oauth-callback.js

@@ -0,0 +1,107 @@
+const http = require("node:http");
+const crypto = require("node:crypto");
+const { OAUTH_TIMEOUT_MS } = require("./constants");
+const {
+  getLoopbackBindHost,
+  parseLoopbackRedirectUri,
+} = require("./redirect-uri");
+
+function writeTextResponse(res, statusCode, body, contentType = "text/plain; charset=utf-8") {
+  res.statusCode = statusCode;
+  res.setHeader("cache-control", "no-store, max-age=0");
+  res.setHeader("pragma", "no-cache");
+  res.setHeader("x-content-type-options", "nosniff");
+  res.setHeader("content-type", contentType);
+  res.end(body);
+}
+
+function stateMatches(expectedState, state) {
+  if (!expectedState || !state) {
+    return false;
+  }
+
+  const expected = Buffer.from(String(expectedState));
+  const actual = Buffer.from(String(state));
+  if (expected.length !== actual.length) {
+    return false;
+  }
+
+  return crypto.timingSafeEqual(expected, actual);
+}
+
+function waitForOAuthCallback(redirectUri, expectedState) {
+  const redirect = parseLoopbackRedirectUri(redirectUri);
+  const hostname = getLoopbackBindHost(redirect.hostname);
+  const port = Number(redirect.port);
+  const path = redirect.pathname || "/";
+
+  return new Promise((resolve, reject) => {
+    const timeoutId = setTimeout(() => {
+      server.close();
+      reject(new Error("Timed out waiting for OAuth callback."));
+    }, OAUTH_TIMEOUT_MS);
+
+    const server = http.createServer((req, res) => {
+      const reqUrl = new URL(req.url || "/", `http://${hostname}:${port}`);
+      if (reqUrl.pathname !== path) {
+        writeTextResponse(res, 404, "Not found");
+        return;
+      }
+
+      const state = reqUrl.searchParams.get("state");
+      const code = reqUrl.searchParams.get("code");
+      const error = reqUrl.searchParams.get("error");
+      const errorDescription = reqUrl.searchParams.get("error_description");
+
+      if (error) {
+        writeTextResponse(res, 400, "Clio authorization failed. You can close this window.");
+        clearTimeout(timeoutId);
+        server.close();
+        reject(
+          new Error(
+            `Authorization failed: ${error}${errorDescription ? ` (${errorDescription})` : ""}`
+          )
+        );
+        return;
+      }
+
+      if (!code) {
+        writeTextResponse(res, 400, "Missing authorization code. You can close this window.");
+        clearTimeout(timeoutId);
+        server.close();
+        reject(new Error("OAuth callback did not include an authorization code."));
+        return;
+      }
+
+      if (!stateMatches(expectedState, state)) {
+        writeTextResponse(res, 400, "Invalid state. You can close this window.");
+        clearTimeout(timeoutId);
+        server.close();
+        reject(new Error("State validation failed for OAuth callback."));
+        return;
+      }
+
+      writeTextResponse(
+        res,
+        200,
+        "<html><body><h3>Clio auth complete</h3><p>You can close this tab and return to the terminal.</p></body></html>",
+        "text/html; charset=utf-8"
+      );
+
+      clearTimeout(timeoutId);
+      server.close();
+      resolve({ code, state });
+    });
+
+    server.on("error", (error) => {
+      clearTimeout(timeoutId);
+      reject(error);
+    });
+
+    server.listen(port, hostname);
+  });
+}
+
+module.exports = {
+  waitForOAuthCallback,
+};

package/src/open-browser.js

@@ -0,0 +1,33 @@
+const { spawn } = require("node:child_process");
+
+function openBrowser(url) {
+  return new Promise((resolve, reject) => {
+    let command = "";
+    let args = [];
+
+    if (process.platform === "darwin") {
+      command = "open";
+      args = [url];
+    } else if (process.platform === "win32") {
+      command = "cmd";
+      args = ["/c", "start", "", url];
+    } else {
+      command = "xdg-open";
+      args = [url];
+    }
+
+    const child = spawn(command, args, {
+      stdio: "ignore",
+      detached: true,
+      windowsHide: true,
+    });
+
+    child.on("error", reject);
+    child.unref();
+    resolve();
+  });
+}
+
+module.exports = {
+  openBrowser,
+};

package/src/postinstall.js

@@ -0,0 +1,140 @@
+const { setupWizard } = require("./commands-auth");
+const { ask, withPrompt } = require("./prompt");
+const { findConfig } = require("./store");
+
+const SKIP_POSTINSTALL_ENV_VARS = [
+  "NOT_MANAGE_SKIP_POSTINSTALL_SETUP",
+  "CLIO_MANAGE_SKIP_POSTINSTALL_SETUP",
+];
+
+function printConfidentialityNotice(log = console.log) {
+  log("Confidentiality notice:");
+  log("  not-manage can display client-identifying, confidential, or privileged matter data.");
+  log("  `--redacted` is best-effort only and may miss identifiers in labels, custom fields, or free text.");
+  log("  Review all output before sharing it with AI tools, tickets, chats, or other third parties.");
+  log("  Use only with workflows and vendors your firm has approved.");
+}
+
+function shouldShowPostinstallNotice(options = {}) {
+  const env = options.env || process.env;
+
+  if (SKIP_POSTINSTALL_ENV_VARS.some((name) => env[name] === "1")) {
+    return false;
+  }
+
+  if (env.CI) {
+    return false;
+  }
+
+  if (env.npm_config_global !== "true") {
+    return false;
+  }
+
+  return true;
+}
+
+function shouldRunPostinstallOnboarding(options = {}) {
+  const stdin = options.stdin || process.stdin;
+  const stdout = options.stdout || process.stdout;
+
+  if (!shouldShowPostinstallNotice(options)) {
+    return false;
+  }
+
+  if (!stdin.isTTY || !stdout.isTTY) {
+    return false;
+  }
+
+  return true;
+}
+
+function printPostinstallIntro(log = console.log) {
+  log("");
+  log("+===========================================+");
+  log("|           NOT MANAGE IS INSTALLED         |");
+  log("+===========================================+");
+  log("|     Start first-time setup from npm?      |");
+  log("+===========================================+");
+  log("");
+  log("This prompt only appears on fresh interactive global installs.");
+  log("If you skip it now, run `not-manage setup` whenever you are ready.");
+  log("");
+  printConfidentialityNotice(log);
+  log("");
+}
+
+function printPostinstallInstalledNotice(log = console.log) {
+  log("");
+  log("not-manage is installed.");
+  printConfidentialityNotice(log);
+  log("Run `not-manage setup` whenever you are ready.");
+}
+
+function printPostinstallWelcomeBack(log = console.log) {
+  log("");
+  log("Welcome back. Clio is already configured on this machine.");
+  log("Run `not-manage auth status` to verify the current connection, or `not-manage setup` to reconfigure.");
+}
+
+async function maybeRunPostinstallOnboarding(options = {}) {
+  const log = options.log || console.log;
+  const findConfigFn = options.findConfig || findConfig;
+  const setupWizardFn = options.setupWizard || setupWizard;
+  const withPromptFn = options.withPrompt || withPrompt;
+  const askFn = options.ask || ask;
+
+  if (!shouldShowPostinstallNotice(options)) {
+    return false;
+  }
+
+  const config = await findConfigFn();
+  if (config) {
+    printPostinstallWelcomeBack(log);
+    return false;
+  }
+
+  if (!shouldRunPostinstallOnboarding(options)) {
+    printPostinstallInstalledNotice(log);
+    return false;
+  }
+
+  printPostinstallIntro(log);
+
+  const answer = String(
+    await withPromptFn((rl) => askFn(rl, "Start guided Clio setup now", "yes"))
+  )
+    .trim()
+    .toLowerCase();
+
+  if (["n", "no", "skip"].includes(answer)) {
+    log("Skipping setup for now. Run `not-manage setup` when you are ready.");
+    return false;
+  }
+
+  await setupWizardFn();
+  return true;
+}
+
+async function main(options = {}) {
+  const log = options.log || console.log;
+  const errorLog = options.errorLog || console.error;
+
+  try {
+    await maybeRunPostinstallOnboarding(options);
+  } catch (error) {
+    errorLog(`Post-install setup was skipped: ${error.message}`);
+    log("Run `not-manage setup` when you are ready.");
+  }
+}
+
+if (require.main === module) {
+  main();
+}
+
+module.exports = {
+  main,
+  maybeRunPostinstallOnboarding,
+  printConfidentialityNotice,
+  shouldShowPostinstallNotice,
+  shouldRunPostinstallOnboarding,
+};

package/src/prompt.js

@@ -0,0 +1,103 @@
+const { Writable } = require("node:stream");
+const { createInterface } = require("node:readline/promises");
+const { stdin, stdout } = require("node:process");
+
+class PromptOutput extends Writable {
+  constructor(target) {
+    super();
+    this.target = target;
+    this.muted = false;
+  }
+
+  _write(chunk, encoding, callback) {
+    if (!this.muted) {
+      writePromptChunk(this.target, chunk, encoding);
+      callback();
+      return;
+    }
+
+    const text = decodePromptChunk(chunk, encoding);
+    if (text === "\n" || text === "\r\n") {
+      writePromptChunk(this.target, chunk, encoding);
+    }
+
+    callback();
+  }
+
+  writeVisible(text) {
+    this.target.write(text);
+  }
+}
+
+function decodePromptChunk(chunk, encoding) {
+  if (typeof chunk === "string") {
+    return chunk;
+  }
+
+  if (encoding && encoding !== "buffer") {
+    return chunk.toString(encoding);
+  }
+
+  return chunk.toString();
+}
+
+function writePromptChunk(target, chunk, encoding) {
+  if (encoding && encoding !== "buffer") {
+    target.write(chunk, encoding);
+    return;
+  }
+
+  target.write(chunk);
+}
+
+async function withPrompt(callback) {
+  const output = new PromptOutput(stdout);
+  const rl = createInterface({
+    input: stdin,
+    output,
+    terminal: true,
+  });
+  rl.__promptOutput = output;
+
+  try {
+    return await callback(rl);
+  } finally {
+    rl.close();
+  }
+}
+
+async function ask(rl, label, fallback = null) {
+  const suffix = fallback ? ` [${fallback}]` : "";
+  const answer = await rl.question(`${label}${suffix}: `);
+  const trimmed = answer.trim();
+  if (trimmed) {
+    return trimmed;
+  }
+  return fallback;
+}
+
+async function askSecret(rl, label) {
+  const output = rl && rl.__promptOutput;
+  if (!output) {
+    return ask(rl, label);
+  }
+
+  output.writeVisible(`${label}: `);
+  output.muted = true;
+
+  try {
+    const answer = await rl.question("");
+    const trimmed = answer.trim();
+    return trimmed || null;
+  } finally {
+    output.muted = false;
+  }
+}
+
+module.exports = {
+  PromptOutput,
+  ask,
+  askSecret,
+  decodePromptChunk,
+  withPrompt,
+};