not-manage 0.2.2 → 0.2.4

package/README.md

@@ -12,16 +12,22 @@ This project is a terminal CLI from [Not Operations](https://notoperations.com/l
 
 ## Install
 
+Before you run the install command, make sure your computer has:
+
+- **Node.js 20 or newer**. Node.js is not installed by default on most computers. Install it from [nodejs.org](https://nodejs.org/); it includes the `npm` command used below.
+- A working OS keychain: macOS Keychain, Windows Credential Manager, or a Linux Secret Service/keyring.
+- A browser and internet access for the Clio login flow.
+
 ```bash
 npm i -g not-manage && not-manage
 ```
 
-The package does not run install-time scripts. Setup starts when you launch `not-manage`.
+`not-manage` itself does not run install-time scripts. npm may still perform normal dependency installation, including the secure keychain dependency used to store credentials locally. `not-manage` opens in help-first mode so you can inspect commands before changing local state.
 
 What happens next:
 
-- first-time setup: `not-manage` starts guided setup
-- returning setup: `not-manage` opens normally and can verify the saved connection
+- first-time setup: run `not-manage auth setup` or `not-manage setup` when you are ready
+- returning setup: `not-manage` opens command help and you can verify the saved connection explicitly
 - setup warning: the CLI reminds you that output may contain confidential client data and that redaction is best-effort only
 
 Network behavior:
@@ -60,7 +66,7 @@ node bin/not-manage.js --help
 not-manage auth setup
 ```
 
-2. Choose your Clio region in the CLI.
+2. Choose your Clio region in the CLI, or pass it directly with `--region`.
 3. When the CLI opens the Clio developer portal, sign in there.
 4. Open your Clio developer app there, or create one first if you do not have one yet.
 5. Fill out the Clio app form:
@@ -88,6 +94,12 @@ During setup, the CLI asks you to acknowledge that:
 - `--redacted` is best-effort only and may miss identifiers in labels, custom fields, or free text
 - you must review output before sharing it with AI tools or other third parties
 
+For non-interactive setup, pass the required values directly:
+
+```bash
+not-manage auth setup --confirm-confidentiality --region us --client-id <app-key> --client-secret <app-secret>
+```
+
 ## Local-only docs
 
 - [PRIVACY.md](PRIVACY.md)
@@ -106,13 +118,37 @@ During setup, the CLI asks you to acknowledge that:
 
 ```bash
 not-manage setup
+not-manage doctor
+not-manage agent-context
 not-manage auth setup
 not-manage auth login
 not-manage auth status
 not-manage whoami
-not-manage auth revoke
+not-manage auth revoke --dry-run
+not-manage auth revoke --yes
+```
+
+## Agent-friendly output
+
+Use `--agent` with any command to apply machine-friendly defaults:
+
+```bash
+not-manage --agent contacts list --query "acme"
 ```
 
+`--agent` implies `--json`, `--compact`, `--no-input`, `--no-color`, and `--yes`. Use `--compact` by itself when you want reduced JSON fields without changing confirmation behavior.
+
+`not-manage agent-context` emits a machine-readable command map for agents. `not-manage doctor --json` reports local setup, token state, and Clio connectivity; add `--fail-on warn` for CI-style checks.
+
+Agents can also pass structured inputs without shell-escaping every filter:
+
+```bash
+not-manage --agent matters list --options-file filters.json
+printf "123\n456\n" | not-manage --agent contacts get --stdin
+```
+
+`--options-file <path|->` merges a JSON object into resource command options, with explicit CLI flags taking precedence. `get` commands also accept `--ids-file <path|->` or `--stdin` for bulk read-only lookups.
+
 ## Resource command reference
 
 <!-- GENERATED:CLI_REFERENCE:start -->
@@ -218,8 +254,14 @@ not-manage matter get 456 --redacted
 - Supported data commands are redacted by default.
 - Add `--unredacted` to show raw output.
 - `--redacted` is still accepted for compatibility.
-- The first version redacts client/contact names, emails, phone numbers, and common PII patterns that appear inside free-text fields such as matter descriptions, activity notes, bill memos, and bill subjects.
+- Redaction covers:
+  - client/contact names (full names, individual first and last names), emails, and phone numbers from structured fields
+  - pattern-based detection of emails, phone numbers, SSNs (dash and space-separated), tax IDs, and credit card numbers (standard 16-digit and American Express 15-digit formats) in all string fields
+  - person client surnames derived from matter labels and used to redact matter numbers, file names, and summaries
+  - significant tokens from company client names (filtering out noise like LLC, Inc, Corp) used to redact matter labels
+  - heuristic detection of bare 2-3 word person names in free-text and label fields
 - Internal staff fields such as `user`, `responsible_attorney`, `responsible_staff`, and `originating_attorney` remain visible.
+- API error messages sanitize URLs to prevent leaking query parameters that may contain PII.
 - Redaction is best-effort only. Review output before sharing it outside your firm or with any AI or third-party service.
 - High-risk commands such as contacts, matters, activities, bills, invoices, tasks, and billable client or matter views emit additional review warnings.
 - `--unredacted` on those high-risk commands emits a stronger warning because raw output may include client-identifying, confidential, or privileged information.

package/bin/not-manage.js

@@ -1,8 +1,21 @@
 #!/usr/bin/env node
 
 const { run } = require("../src/cli");
+const { CliError, reportError } = require("../src/cli-errors");
 
-run(process.argv.slice(2)).catch((_error) => {
-  console.error("Error: command failed.");
+const args = process.argv.slice(2);
+const jsonMode = args.includes("--agent") ||
+  args.includes("--json") ||
+  args.some((arg) => arg === "--json=true" || arg === "--agent=true");
+
+run(args).catch((error) => {
+  if (error instanceof CliError) {
+    const exitCode = reportError(error, { json: jsonMode });
+    process.exit(exitCode);
+    return;
+  }
+
+  const message = error && error.message ? error.message : "Error: command failed.";
+  console.error(message);
   process.exit(1);
 });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "not-manage",
-  "version": "0.2.2",
+  "version": "0.2.4",
   "description": "Unofficial command-line tool for Clio Manage integrations",
   "license": "Apache-2.0",
   "private": false,

package/src/agent-input.js

@@ -0,0 +1,101 @@
+const fs = require("node:fs/promises");
+
+const { UsageError } = require("./cli-errors");
+
+async function readTextInput(source, label) {
+  if (source === "-") {
+    return new Promise((resolve, reject) => {
+      let body = "";
+      process.stdin.setEncoding("utf8");
+      process.stdin.on("data", (chunk) => {
+        body += chunk;
+      });
+      process.stdin.on("end", () => resolve(body));
+      process.stdin.on("error", reject);
+    });
+  }
+
+  try {
+    return await fs.readFile(source, "utf8");
+  } catch (error) {
+    throw new UsageError(`Could not read ${label} from ${source}: ${error.message}`, {
+      code: "input_file_unreadable",
+      hint: "Use a readable file path, or `-` to read from stdin.",
+    });
+  }
+}
+
+async function readJsonInput(source, label) {
+  const text = await readTextInput(source, label);
+  try {
+    return JSON.parse(text);
+  } catch (error) {
+    throw new UsageError(`${label} must contain valid JSON: ${error.message}`, {
+      code: "invalid_json_input",
+      hint: "Pass a JSON object, for example `{ \"limit\": 5 }`.",
+    });
+  }
+}
+
+function collectIdsFromValue(value, ids) {
+  if (value === undefined || value === null) {
+    return;
+  }
+
+  if (Array.isArray(value)) {
+    value.forEach((item) => collectIdsFromValue(item, ids));
+    return;
+  }
+
+  if (typeof value === "object") {
+    if (value.id !== undefined && value.id !== null) {
+      collectIdsFromValue(value.id, ids);
+    }
+    return;
+  }
+
+  const text = String(value).trim();
+  if (text) {
+    ids.push(text);
+  }
+}
+
+function parseIdsText(text) {
+  const trimmed = String(text || "").trim();
+  if (!trimmed) {
+    return [];
+  }
+
+  if (trimmed.startsWith("[") || trimmed.startsWith("{")) {
+    const ids = [];
+    try {
+      collectIdsFromValue(JSON.parse(trimmed), ids);
+      return [...new Set(ids)];
+    } catch (_error) {
+      throw new UsageError("ID input must be newline-delimited IDs or JSON containing IDs.", {
+        code: "invalid_ids_input",
+        hint: "Use one ID per line, a JSON array of IDs, or objects with an `id` field.",
+      });
+    }
+  }
+
+  return [
+    ...new Set(
+      trimmed
+        .split(/[\r\n,]+/)
+        .map((line) => line.trim())
+        .filter(Boolean)
+    ),
+  ];
+}
+
+async function readIdsInput(source) {
+  return parseIdsText(await readTextInput(source, "ID input"));
+}
+
+module.exports = {
+  parseIdsText,
+  readIdsInput,
+  readJsonInput,
+  readTextInput,
+};

package/src/cli-errors.js

@@ -0,0 +1,109 @@
+const EXIT_CODES = {
+  unknown: 1,
+  usage: 2,
+  auth: 3,
+  network: 4,
+  api: 5,
+  redaction: 6,
+};
+
+class CliError extends Error {
+  constructor(message, options = {}) {
+    super(message);
+    this.name = "CliError";
+    this.category = options.category || "unknown";
+    this.code = options.code || this.category;
+    this.exitCode = options.exitCode || EXIT_CODES[this.category] || EXIT_CODES.unknown;
+    this.hint = options.hint;
+    this.docsUrl = options.docsUrl;
+    if (options.details && typeof options.details === "object") {
+      this.details = options.details;
+    }
+  }
+}
+
+class UsageError extends CliError {
+  constructor(message, options = {}) {
+    super(message, { ...options, category: "usage", exitCode: EXIT_CODES.usage });
+    this.name = "UsageError";
+  }
+}
+
+class AuthError extends CliError {
+  constructor(message, options = {}) {
+    super(message, { ...options, category: "auth", exitCode: EXIT_CODES.auth });
+    this.name = "AuthError";
+  }
+}
+
+class NetworkError extends CliError {
+  constructor(message, options = {}) {
+    super(message, { ...options, category: "network", exitCode: EXIT_CODES.network });
+    this.name = "NetworkError";
+  }
+}
+
+class ApiError extends CliError {
+  constructor(message, options = {}) {
+    super(message, { ...options, category: "api", exitCode: EXIT_CODES.api });
+    this.name = "ApiError";
+  }
+}
+
+class RedactionError extends CliError {
+  constructor(message, options = {}) {
+    super(message, { ...options, category: "redaction", exitCode: EXIT_CODES.redaction });
+    this.name = "RedactionError";
+  }
+}
+
+function toErrorEnvelope(error) {
+  const isCliError = error instanceof CliError;
+  const message = (error && error.message ? String(error.message) : "Command failed.").trim();
+  const category = isCliError ? error.category : "unknown";
+  const code = isCliError ? error.code : "unknown";
+  const exitCode = isCliError ? error.exitCode : EXIT_CODES.unknown;
+  const envelope = {
+    error: {
+      code,
+      category,
+      message,
+      exit_code: exitCode,
+    },
+  };
+  if (isCliError && error.hint) {
+    envelope.error.hint = error.hint;
+  }
+  if (isCliError && error.docsUrl) {
+    envelope.error.docs_url = error.docsUrl;
+  }
+  if (isCliError && error.details) {
+    envelope.error.details = error.details;
+  }
+  return envelope;
+}
+
+function reportError(error, { json = false, stderr = process.stderr } = {}) {
+  const envelope = toErrorEnvelope(error);
+  if (json) {
+    stderr.write(`${JSON.stringify(envelope)}\n`);
+  } else {
+    stderr.write(`${envelope.error.message}\n`);
+    if (envelope.error.hint) {
+      stderr.write(`Hint: ${envelope.error.hint}\n`);
+    }
+  }
+  return envelope.error.exit_code;
+}
+
+module.exports = {
+  ApiError,
+  AuthError,
+  CliError,
+  EXIT_CODES,
+  NetworkError,
+  RedactionError,
+  UsageError,
+  reportError,
+  toErrorEnvelope,
+};