not-manage 0.2.1 → 0.2.3

package/src/clio-api.js

@@ -1,8 +1,106 @@
 const { saveTokenSet } = require("./store");
 
-function createError(message, responseText) {
-  const suffix = responseText ? ` ${responseText}` : "";
-  return new Error(`${message}.${suffix}`.trim());
+function sanitizeUrlForError(url) {
+  try {
+    const parsed = new URL(url);
+    if (parsed.search) {
+      return `${parsed.origin}${parsed.pathname}?[query redacted]`;
+    }
+    return `${parsed.origin}${parsed.pathname}`;
+  } catch (_error) {
+    return "[invalid URL]";
+  }
+}
+
+function toSafeErrorToken(value) {
+  const text = String(value || "").trim();
+  if (!text || !/^[a-z0-9_.:-]+$/i.test(text)) {
+    return null;
+  }
+
+  return text;
+}
+
+function extractErrorCodes(payload) {
+  if (!isPlainObject(payload)) {
+    return [];
+  }
+
+  const codes = [];
+
+  ["error", "code", "type", "error_code"].forEach((key) => {
+    const safeToken = toSafeErrorToken(payload[key]);
+    if (safeToken) {
+      codes.push(safeToken);
+    }
+  });
+
+  if (Array.isArray(payload.errors)) {
+    payload.errors.forEach((item) => {
+      if (!isPlainObject(item)) {
+        return;
+      }
+
+      ["error", "code", "type", "error_code"].forEach((key) => {
+        const safeToken = toSafeErrorToken(item[key]);
+        if (safeToken) {
+          codes.push(safeToken);
+        }
+      });
+    });
+  }
+
+  return [...new Set(codes)];
+}
+
+function summarizeErrorPayload(payload) {
+  if (payload === null || payload === undefined || payload === "") {
+    return "";
+  }
+
+  const errorCodes = extractErrorCodes(payload);
+  if (errorCodes.length === 1) {
+    return `Clio error code: ${errorCodes[0]}.`;
+  }
+
+  if (errorCodes.length > 1) {
+    return `Clio error codes: ${errorCodes.join(", ")}.`;
+  }
+
+  if (typeof payload === "string") {
+    return "Response body omitted.";
+  }
+
+  if (Array.isArray(payload)) {
+    const noun = payload.length === 1 ? "item" : "items";
+    return `Clio returned ${payload.length} error ${noun}.`;
+  }
+
+  if (isPlainObject(payload)) {
+    if (Array.isArray(payload.errors)) {
+      const count = payload.errors.length;
+      const noun = count === 1 ? "item" : "items";
+      return `Clio returned ${count} error ${noun}.`;
+    }
+
+    return "Response body omitted.";
+  }
+
+  return "";
+}
+
+function createError(message, payload) {
+  const sanitizedMessage = message.replace(
+    /https?:\/\/\S+/g,
+    (match) => sanitizeUrlForError(match)
+  );
+  const summary = summarizeErrorPayload(payload);
+  const error = new Error(summary ? `${sanitizedMessage}. ${summary}` : `${sanitizedMessage}.`);
+  const [clioErrorCode] = extractErrorCodes(payload);
+  if (clioErrorCode) {
+    error.clioErrorCode = clioErrorCode;
+  }
+  return error;
 }
 
 function isPlainObject(value) {
@@ -33,7 +131,7 @@ async function postForm(url, formFields, headers = {}) {
   if (!response.ok) {
     throw createError(
       `HTTP ${response.status} from ${url}`,
-      typeof payload === "string" ? payload : JSON.stringify(payload)
+      payload
     );
   }
 
@@ -59,7 +157,7 @@ async function getJson(url, headers = {}) {
   if (!response.ok) {
     throw createError(
       `HTTP ${response.status} from ${url}`,
-      typeof payload === "string" ? payload : JSON.stringify(payload)
+      payload
     );
   }
 
@@ -91,7 +189,7 @@ async function postJson(url, body, headers = {}) {
   if (!response.ok) {
     throw createError(
       `HTTP ${response.status} from ${url}`,
-      typeof payload === "string" ? payload : JSON.stringify(payload)
+      payload
     );
   }
 
@@ -411,6 +509,10 @@ module.exports = {
   getValidAccessToken,
   __private: {
     buildUrlWithQuery,
+    createError,
+    extractErrorCodes,
     parseTrustedApiUrl,
+    sanitizeUrlForError,
+    summarizeErrorPayload,
   },
 };

package/src/commands-agent-context.js

@@ -0,0 +1,119 @@
+const { RESOURCE_ORDER, getResourceMetadata } = require("./resource-metadata");
+const { version } = require("../package.json");
+
+const SCHEMA_VERSION = 1;
+
+function buildGlobalCommands() {
+  return [
+    {
+      name: "setup",
+      use: "not-manage setup",
+      description: "Run guided setup and OAuth login.",
+    },
+    {
+      name: "doctor",
+      use: "not-manage doctor [--json] [--fail-on warn|error]",
+      description: "Report local configuration, auth, and Clio connectivity status.",
+      readOnly: true,
+    },
+    {
+      name: "agent-context",
+      use: "not-manage agent-context [--json]",
+      description: "Emit this machine-readable command and resource catalog.",
+      readOnly: true,
+    },
+    {
+      name: "auth",
+      use: "not-manage auth <setup|login|status|revoke>",
+      description: "Manage local OAuth configuration and token state.",
+    },
+    {
+      name: "whoami",
+      use: "not-manage whoami [--json]",
+      description: "Call Clio's current-user endpoint.",
+      readOnly: true,
+    },
+    {
+      name: "request",
+      use: "not-manage request <method> <path> [--query k=v] [--write] [--dry-run] [--json]",
+      description: "Raw API escape hatch that reuses saved auth and redaction.",
+    },
+  ];
+}
+
+function buildResourceCommand(command) {
+  const metadata = getResourceMetadata(command);
+  const subcommands = ["list", "get"]
+    .filter((subcommand) => metadata.capabilities[subcommand].enabled)
+    .map((subcommand) => ({
+      name: subcommand,
+      use:
+        subcommand === "get"
+          ? `not-manage ${command} get <id> [options]`
+          : `not-manage ${command} list [options]`,
+      description: metadata.help[subcommand],
+      readOnly: true,
+      requiredOptions: metadata.capabilities[subcommand].requiredOptions || [],
+      options: Object.values(metadata.optionSchema?.[subcommand] || {})
+        .filter((option) => option.positional === undefined)
+        .map((option) => ({
+          name: `--${option.option}`,
+          kind: option.kind || "string",
+        }))
+        .concat(
+          [
+            { name: "--options-file", kind: "string" },
+            subcommand === "get" ? { name: "--ids-file", kind: "string" } : null,
+            subcommand === "get" ? { name: "--stdin", kind: "flag" } : null,
+          ].filter(Boolean)
+        ),
+    }));
+
+  return {
+    name: command,
+    aliases: metadata.aliases,
+    subcommands,
+  };
+}
+
+async function agentContext(options = {}) {
+  const payload = {
+    schemaVersion: SCHEMA_VERSION,
+    cli: {
+      name: "not-manage",
+      version,
+      description: "Unofficial command-line tool for Clio Manage integrations.",
+    },
+    defaults: {
+      dataCommandsRedacted: true,
+      agentFlagImplies: ["--json", "--compact", "--no-input", "--no-color", "--yes"],
+    },
+    auth: {
+      mode: "oauth2_loopback",
+      credentialStorage: "os_keychain",
+      tokenStorage: "os_keychain",
+    },
+    globalOptions: [
+      "--agent",
+      "--json",
+      "--compact",
+      "--no-input",
+      "--no-color",
+      "--yes",
+      "--force",
+      "--redacted",
+      "--unredacted",
+    ],
+    commands: buildGlobalCommands(),
+    resources: RESOURCE_ORDER.map(buildResourceCommand),
+  };
+
+  console.log(JSON.stringify(payload, null, options.compact ? 0 : 2));
+}
+
+module.exports = {
+  agentContext,
+  __private: {
+    buildResourceCommand,
+  },
+};