not-manage 0.2.0 → 0.2.1

package/README.md

@@ -48,6 +48,7 @@ For local development:
 git clone https://github.com/Not-Operations/not-manage.git
 cd not-manage
 npm install
+npm run hooks:install
 node bin/not-manage.js --help
 ```
 
@@ -95,6 +96,11 @@ During setup, the CLI asks you to acknowledge that:
 - [SECURITY.md](SECURITY.md)
 - [TERMS.md](TERMS.md)
 - [OPERATIONS.md](OPERATIONS.md)
+- [SUPPORT.md](SUPPORT.md)
+- [CUSTOMER-TESTING.md](CUSTOMER-TESTING.md)
+- [SUBPROCESSORS.md](SUBPROCESSORS.md)
+- [MVSP-SELF-ASSESSMENT.md](MVSP-SELF-ASSESSMENT.md)
+- [CLIO-APP-DIRECTORY-CHECKLIST.md](CLIO-APP-DIRECTORY-CHECKLIST.md)
 
 ## Core commands
 
@@ -103,34 +109,63 @@ not-manage setup
 not-manage auth setup
 not-manage auth login
 not-manage auth status
-not-manage activities list
-not-manage activity get 123
-not-manage tasks list
-not-manage task get 789
-not-manage contacts list
-not-manage contact get 12345
-not-manage time-entries list
-not-manage billable-clients list
-not-manage billable-matters list
-not-manage bills list
-not-manage bill get 987
-not-manage invoices list
-not-manage matters list
-not-manage matter get 456
-not-manage users list
-not-manage user get 123
-not-manage practice-areas list
-not-manage practice-area get 45
-not-manage matters list --status open --limit 50
-not-manage matters list --all --json
 not-manage whoami
 not-manage auth revoke
 ```
 
+## Resource command reference
+
+<!-- GENERATED:CLI_REFERENCE:start -->
+This table is generated from resource metadata. Global auth/setup commands stay hand-written.
+
+| Command | Operations | Aliases | Required list filters |
+| --- | --- | --- | --- |
+| `activities` | `list`, `get` | `activity` | - |
+| `calendar-entries` | `list`, `get` | `calendar-entry` | - |
+| `reminders` | `list`, `get` | `reminder` | - |
+| `tasks` | `list`, `get` | `task` | - |
+| `contacts` | `list`, `get` | `contact` | - |
+| `communications` | `list`, `get` | `communication` | - |
+| `conversations` | `list`, `get` | `conversation` | - |
+| `conversation-messages` | `list`, `get` | `conversation-message` | `--conversation-id` |
+| `notes` | `list`, `get` | `note` | `--type` |
+| `custom-fields` | `list`, `get` | `custom-field` | - |
+| `time-entries` | `list`, `get` | `time-entry` | - |
+| `billable-clients` | `list` | `billable-client` | - |
+| `billable-matters` | `list` | `billable-matter` | - |
+| `bills` | `list`, `get` | `bill` | - |
+| `invoices` | `list`, `get` | `invoice` | - |
+| `outstanding-client-balances` | `list` | `outstanding-client-balance` | - |
+| `matters` | `list`, `get` | `matter` | - |
+| `matter-dockets` | `list`, `get` | `matter-docket` | - |
+| `users` | `list`, `get` | `user` | - |
+| `practice-areas` | `list`, `get` | `practice-area` | - |
+| `my-events` | `list` | `my-event` | - |
+
+Required list filters are enforced by the CLI before it calls Clio.
+<!-- GENERATED:CLI_REFERENCE:end -->
+
 Plural commands still work. Singular aliases are accepted for the single-record flows so `contact get 12345` and `contacts get 12345` both work.
 
 Every data command also accepts `--fields <comma-separated-list>` to override the default response shape. If you pass `--fields` with no value, the CLI prints the current default field list for that command.
 
+## Live smoke checks
+
+In a local checkout, if you already have an authenticated test account, you can run a safe read-only smoke pass:
+
+```bash
+npm run smoke:live
+```
+
+This exercises a small set of real CLI reads against the currently authenticated Clio account:
+
+- `auth status`
+- `whoami`
+- `users list`
+- `notes list --type Matter`
+- `outstanding-client-balances list`
+- `calendar-entries list`
+
 ## Read-only examples
 
 ```bash
@@ -165,6 +200,14 @@ not-manage practice-areas list --name "Family"
 not-manage practice-areas list --matter-id 456
 not-manage practice-area get 45
 
+not-manage calendar-entries list --from 2026-03-01T00:00:00Z --to 2026-03-31T23:59:59Z
+not-manage reminders list --state pending
+not-manage notes list --type Matter --limit 25
+not-manage conversation-messages list --conversation-id 123
+not-manage outstanding-client-balances list --limit 25
+not-manage matter-dockets list --matter-id 456
+not-manage my-events list --limit 25
+
 not-manage billable-matters list --client-id 999
 not-manage billable-clients list --start-date 2026-03-01
 not-manage matter get 456 --redacted
@@ -201,6 +244,13 @@ not-manage matter get 456 --redacted
 - Dependabot is configured for both npm dependencies and GitHub Actions.
 - npm release publishing is set up for provenance-backed trusted publishing from GitHub Actions using the `npm` environment.
 
+## Support
+
+- Public support page: [SUPPORT.md](SUPPORT.md)
+- Public support contact: `hello@notoperations.com`
+- Bug reports and feature requests: `https://github.com/Not-Operations/not-manage/issues`
+- Security reports: see [SECURITY.md](SECURITY.md)
+
 ## Troubleshooting
 
 - `OS keychain ... failed`: re-enable your OS keychain service or run the CLI in a supported desktop session with keychain access.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "not-manage",
-  "version": "0.2.0",
+  "version": "0.2.1",
   "description": "Unofficial command-line tool for Clio Manage integrations",
   "license": "Apache-2.0",
   "private": false,
@@ -31,14 +31,18 @@
     "cli"
   ],
   "scripts": {
-    "check": "npm run check:syntax && npm test",
+    "check": "npm run check:syntax && npm test && npm run docs:check",
     "check:security": "npm audit --audit-level=high",
-    "check:syntax": "node --check bin/not-manage.js && node --check src/*.js && node --check test/*.test.js && node --check test/helpers/*.js",
+    "check:syntax": "node --check bin/not-manage.js && node --check src/*.js && node --check scripts/*.js && node --check test/*.test.js && node --check test/helpers/*.js",
     "dev": "node bin/not-manage.js",
+    "docs:check": "node scripts/generate-readme-cli-reference.js --check",
+    "docs:generate": "node scripts/generate-readme-cli-reference.js",
+    "hooks:install": "node scripts/install-git-hooks.js",
     "pack:check": "npm pack --dry-run",
     "postinstall": "node src/postinstall.js",
     "seed:handbook-imports": "node scripts/generate-handbook-import-csvs.js",
     "seed:historical": "node scripts/seed-historical-data.js",
+    "smoke:live": "node scripts/smoke-read-only-live.js",
     "start": "node bin/not-manage.js",
     "test": "node --test test/*.test.js"
   },

package/src/cli-options.js

@@ -2,6 +2,10 @@ function hasOwn(object, key) {
   return Object.prototype.hasOwnProperty.call(object, key);
 }
 
+function isPlainObject(value) {
+  return Boolean(value) && typeof value === "object" && !Array.isArray(value);
+}
+
 function normalizeOptionName(name) {
   return String(name).replace(/^--/, "");
 }
@@ -23,6 +27,20 @@ function hasFlag(args, ...flags) {
   return flags.some((flag) => args.includes(flag));
 }
 
+function appendParsedValue(parsed, key, value) {
+  if (!hasOwn(parsed, key)) {
+    parsed[key] = value;
+    return;
+  }
+
+  if (Array.isArray(parsed[key])) {
+    parsed[key].push(value);
+    return;
+  }
+
+  parsed[key] = [parsed[key], value];
+}
+
 function parseOptions(args) {
   const parsed = {};
   const positional = [];
@@ -39,35 +57,61 @@ function parseOptions(args) {
     const inlineValue = rest.length > 0 ? rest.join("=") : null;
 
     if (inlineValue !== null) {
-      parsed[rawKey] = inlineValue;
+      appendParsedValue(parsed, rawKey, inlineValue);
       continue;
     }
 
     const next = args[index + 1];
     if (next && !next.startsWith("--")) {
-      parsed[rawKey] = next;
+      appendParsedValue(parsed, rawKey, next);
       index += 1;
       continue;
     }
 
-    parsed[rawKey] = true;
+    appendParsedValue(parsed, rawKey, true);
   }
 
   return { parsed, positional };
 }
 
-function readOption(parsedOptions, name) {
-  for (const candidate of optionKeyCandidates(name)) {
-    if (hasOwn(parsedOptions, candidate)) {
-      return parsedOptions[candidate];
+function normalizeOptionValues(value) {
+  if (value === undefined) {
+    return [];
+  }
+
+  return Array.isArray(value) ? value : [value];
+}
+
+function readOptionValues(parsedOptions, name) {
+  return optionKeyCandidates(name).reduce((values, candidate) => {
+    if (!hasOwn(parsedOptions, candidate)) {
+      return values;
     }
+
+    return values.concat(normalizeOptionValues(parsedOptions[candidate]));
+  }, []);
+}
+
+function readOption(parsedOptions, name) {
+  const values = readOptionValues(parsedOptions, name);
+  if (values.length === 0) {
+    return undefined;
+  }
+
+  return values.length === 1 ? values[0] : values;
+}
+
+function readLastOptionValue(parsedOptions, name) {
+  const values = readOptionValues(parsedOptions, name);
+  if (values.length === 0) {
+    return undefined;
   }
 
-  return undefined;
+  return values[values.length - 1];
 }
 
 function readStringOption(parsedOptions, name) {
-  const value = readOption(parsedOptions, name);
+  const value = readLastOptionValue(parsedOptions, name);
   if (value === undefined) {
     return undefined;
   }
@@ -79,6 +123,34 @@ function readStringOption(parsedOptions, name) {
   return String(value);
 }
 
+function splitCommaSeparatedValues(text) {
+  return String(text)
+    .split(",")
+    .map((value) => value.trim())
+    .filter(Boolean);
+}
+
+function readStringArrayOption(parsedOptions, name) {
+  const values = readOptionValues(parsedOptions, name);
+  if (values.length === 0) {
+    return undefined;
+  }
+
+  const output = [];
+
+  values.forEach((value) => {
+    if (value === true) {
+      throw new Error(`\`--${toKebabCase(name)}\` requires a value.`);
+    }
+
+    splitCommaSeparatedValues(value).forEach((item) => {
+      output.push(item);
+    });
+  });
+
+  return output.length > 0 ? output : undefined;
+}
+
 function parseBooleanValue(value, name) {
   if (value === true || value === false) {
     return value;
@@ -98,7 +170,7 @@ function parseBooleanValue(value, name) {
 }
 
 function readBooleanOption(parsedOptions, name) {
-  const value = readOption(parsedOptions, name);
+  const value = readLastOptionValue(parsedOptions, name);
   if (value === undefined) {
     return undefined;
   }
@@ -156,6 +228,185 @@ function readIsoDateTimeOption(parsedOptions, name) {
   return validateIsoDateTime(value, name);
 }
 
+function readIsoDateArrayOption(parsedOptions, name) {
+  const values = readStringArrayOption(parsedOptions, name);
+  if (values === undefined) {
+    return undefined;
+  }
+
+  return values.map((value) => validateIsoDate(value, name));
+}
+
+function readIsoDateTimeArrayOption(parsedOptions, name) {
+  const values = readStringArrayOption(parsedOptions, name);
+  if (values === undefined) {
+    return undefined;
+  }
+
+  return values.map((value) => validateIsoDateTime(value, name));
+}
+
+function splitTopLevel(text, delimiter = ",") {
+  const segments = [];
+  let current = "";
+  let depth = 0;
+  let quote = null;
+  let escapeNext = false;
+
+  for (const char of String(text)) {
+    if (escapeNext) {
+      current += char;
+      escapeNext = false;
+      continue;
+    }
+
+    if (quote) {
+      current += char;
+      if (char === "\\") {
+        escapeNext = true;
+      } else if (char === quote) {
+        quote = null;
+      }
+      continue;
+    }
+
+    if (char === "'" || char === '"') {
+      quote = char;
+      current += char;
+      continue;
+    }
+
+    if (char === "[" || char === "{") {
+      depth += 1;
+      current += char;
+      continue;
+    }
+
+    if (char === "]" || char === "}") {
+      depth = Math.max(0, depth - 1);
+      current += char;
+      continue;
+    }
+
+    if (char === delimiter && depth === 0) {
+      if (current.trim()) {
+        segments.push(current.trim());
+      }
+      current = "";
+      continue;
+    }
+
+    current += char;
+  }
+
+  if (current.trim()) {
+    segments.push(current.trim());
+  }
+
+  return segments;
+}
+
+function unwrapQuotedValue(value) {
+  const text = String(value).trim();
+  if (
+    (text.startsWith('"') && text.endsWith('"')) ||
+    (text.startsWith("'") && text.endsWith("'"))
+  ) {
+    return text.slice(1, -1);
+  }
+  return text;
+}
+
+function parseStructuredValue(rawValue) {
+  const text = String(rawValue).trim();
+  if (!text) {
+    return "";
+  }
+
+  if (
+    (text.startsWith("{") && text.endsWith("}")) ||
+    (text.startsWith("[") && text.endsWith("]")) ||
+    (text.startsWith('"') && text.endsWith('"'))
+  ) {
+    try {
+      return JSON.parse(text);
+    } catch (_error) {
+      if (text.startsWith("[") && text.endsWith("]")) {
+        return splitTopLevel(text.slice(1, -1)).map((item) => unwrapQuotedValue(item));
+      }
+    }
+  }
+
+  return unwrapQuotedValue(text);
+}
+
+function mergeStructuredValues(existingValue, nextValue) {
+  if (existingValue === undefined) {
+    return nextValue;
+  }
+
+  if (isPlainObject(existingValue) && isPlainObject(nextValue)) {
+    return Object.entries(nextValue).reduce((merged, [key, value]) => {
+      merged[key] = mergeStructuredValues(merged[key], value);
+      return merged;
+    }, { ...existingValue });
+  }
+
+  const existingItems = Array.isArray(existingValue) ? existingValue : [existingValue];
+  const nextItems = Array.isArray(nextValue) ? nextValue : [nextValue];
+  return existingItems.concat(nextItems);
+}
+
+function parseObjectEntries(rawValue, name) {
+  const text = String(rawValue).trim();
+  if (!text) {
+    throw new Error(`\`--${toKebabCase(name)}\` requires a value.`);
+  }
+
+  if (text.startsWith("{")) {
+    const parsed = parseStructuredValue(text);
+    if (!isPlainObject(parsed)) {
+      throw new Error(`\`--${toKebabCase(name)}\` must be an object or key=value pairs.`);
+    }
+    return parsed;
+  }
+
+  return splitTopLevel(text).reduce((output, entry) => {
+    const separatorIndex = entry.search(/[:=]/);
+    if (separatorIndex <= 0) {
+      throw new Error(
+        `\`--${toKebabCase(name)}\` entries must look like \`field=value\` or JSON.`
+      );
+    }
+
+    const key = entry.slice(0, separatorIndex).trim();
+    const value = entry.slice(separatorIndex + 1).trim();
+    if (!key) {
+      throw new Error(
+        `\`--${toKebabCase(name)}\` entries must include a field identifier before \`=\` or \`:\`.`
+      );
+    }
+
+    output[key] = mergeStructuredValues(output[key], parseStructuredValue(value));
+    return output;
+  }, {});
+}
+
+function readObjectOption(parsedOptions, name) {
+  const values = readOptionValues(parsedOptions, name);
+  if (values.length === 0) {
+    return undefined;
+  }
+
+  return values.reduce((output, value) => {
+    if (value === true) {
+      throw new Error(`\`--${toKebabCase(name)}\` requires a value.`);
+    }
+
+    return mergeStructuredValues(output, parseObjectEntries(value, name));
+  }, undefined);
+}
+
 function readCommandOptions(parsedOptions, schema, positional = [], baseOptions = {}, fixed = {}) {
   const options = { ...baseOptions };
 
@@ -175,9 +426,21 @@ function readCommandOptions(parsedOptions, schema, positional = [], baseOptions
       case "iso-date":
         options[propertyName] = readIsoDateOption(parsedOptions, optionDef.option);
         return;
+      case "iso-date-array":
+        options[propertyName] = readIsoDateArrayOption(parsedOptions, optionDef.option);
+        return;
       case "iso-datetime":
         options[propertyName] = readIsoDateTimeOption(parsedOptions, optionDef.option);
         return;
+      case "iso-datetime-array":
+        options[propertyName] = readIsoDateTimeArrayOption(parsedOptions, optionDef.option);
+        return;
+      case "object":
+        options[propertyName] = readObjectOption(parsedOptions, optionDef.option);
+        return;
+      case "string-array":
+        options[propertyName] = readStringArrayOption(parsedOptions, optionDef.option);
+        return;
       case "string":
       default:
         options[propertyName] = readStringOption(parsedOptions, optionDef.option);
@@ -197,8 +460,13 @@ module.exports = {
   readCommandOptions,
   readFlagOption,
   readIsoDateOption,
+  readIsoDateArrayOption,
   readIsoDateTimeOption,
+  readIsoDateTimeArrayOption,
+  readObjectOption,
   readOption,
+  readOptionValues,
   readStringOption,
+  readStringArrayOption,
   toKebabCase,
 };

package/src/cli.js

@@ -7,60 +7,16 @@ const {
   setupWizard,
   whoAmI,
 } = require("./commands-auth");
-const { activitiesGet, activitiesList } = require("./commands-activities");
-const { billableClientsList } = require("./commands-billable-clients");
-const { billableMattersList } = require("./commands-billable-matters");
-const { billsGet, billsList } = require("./commands-bills");
-const { contactsGet, contactsList } = require("./commands-contacts");
-const { mattersGet, mattersList } = require("./commands-matters");
-const { practiceAreasGet, practiceAreasList } = require("./commands-practice-areas");
-const { tasksGet, tasksList } = require("./commands-tasks");
-const { usersGet, usersList } = require("./commands-users");
 const { hasFlag, parseOptions, readBooleanOption, readCommandOptions } = require("./cli-options");
+const { getResourceHandler } = require("./resource-handlers");
 const {
   RESOURCE_ORDER,
   getResourceMetadata,
+  listRequiredOptionFlags,
   normalizeResourceCommand,
 } = require("./resource-metadata");
 const { version } = require("../package.json");
 
-const RESOURCE_HANDLERS = {
-  activities: {
-    get: activitiesGet,
-    list: activitiesList,
-  },
-  "billable-clients": {
-    list: billableClientsList,
-  },
-  "billable-matters": {
-    list: billableMattersList,
-  },
-  bills: {
-    get: billsGet,
-    list: billsList,
-  },
-  contacts: {
-    get: contactsGet,
-    list: contactsList,
-  },
-  matters: {
-    get: mattersGet,
-    list: mattersList,
-  },
-  "practice-areas": {
-    get: practiceAreasGet,
-    list: practiceAreasList,
-  },
-  tasks: {
-    get: tasksGet,
-    list: tasksList,
-  },
-  users: {
-    get: usersGet,
-    list: usersList,
-  },
-};
-
 function maybePrintDefaultFields(command, sub, optionValues) {
   if (optionValues.fields !== true) {
     return false;
@@ -134,12 +90,15 @@ function printHelp() {
   RESOURCE_ORDER.forEach((command) => {
     const resourceMetadata = getResourceMetadata(command);
     ["list", "get"].forEach((sub) => {
-      if (!resourceMetadata.supports[sub]) {
+      if (!resourceMetadata.capabilities[sub].enabled) {
         return;
       }
 
       const usage = `${command} ${sub}`.padEnd(18, " ");
-      console.log(`  ${usage} ${resourceMetadata.help[sub]}`);
+      const requiredFlags = listRequiredOptionFlags(resourceMetadata, sub);
+      const requirementNote =
+        requiredFlags.length > 0 ? ` (requires ${requiredFlags.join(", ")})` : "";
+      console.log(`  ${usage} ${resourceMetadata.help[sub]}${requirementNote}`);
     });
   });
 
@@ -231,9 +190,7 @@ async function run(args) {
   }
 
   const resourceMetadata = getResourceMetadata(command);
-  const handler = resourceMetadata
-    ? RESOURCE_HANDLERS[resourceMetadata.handlerKey]?.[sub]
-    : null;
+  const handler = getResourceHandler(resourceMetadata, sub);
 
   if (resourceMetadata && handler) {
     warnAboutRedaction(resourceMetadata, sub, optionValues, redacted);

package/src/clio-api.js

@@ -5,6 +5,10 @@ function createError(message, responseText) {
   return new Error(`${message}.${suffix}`.trim());
 }
 
+function isPlainObject(value) {
+  return Boolean(value) && typeof value === "object" && !Array.isArray(value);
+}
+
 async function postForm(url, formFields, headers = {}) {
   const response = await fetch(url, {
     method: "POST",
@@ -136,21 +140,45 @@ function parseTrustedApiUrl(config, url, expectedPathPrefix = "/api/v4/") {
 function buildUrlWithQuery(baseUrl, query = {}) {
   const url = new URL(baseUrl);
 
-  Object.entries(query).forEach(([key, value]) => {
+  function appendQueryValue(key, value) {
     if (value === undefined || value === null || value === "") {
       return;
     }
 
     if (Array.isArray(value)) {
       value.forEach((item) => {
-        if (item !== undefined && item !== null && item !== "") {
-          url.searchParams.append(key, String(item));
+        appendQueryValue(key, item);
+      });
+      return;
+    }
+
+    if (isPlainObject(value)) {
+      Object.entries(value).forEach(([nestedKey, nestedValue]) => {
+        if (nestedValue === undefined || nestedValue === null || nestedValue === "") {
+          return;
         }
+
+        const compositeKey = `${key}[${nestedKey}]`;
+        if (Array.isArray(nestedValue)) {
+          const serialized = nestedValue
+            .filter((item) => item !== undefined && item !== null && item !== "")
+            .map((item) => String(item));
+          if (serialized.length > 0) {
+            url.searchParams.append(compositeKey, `[${serialized.join(", ")}]`);
+          }
+          return;
+        }
+
+        appendQueryValue(compositeKey, nestedValue);
       });
       return;
     }
 
-    url.searchParams.set(key, String(value));
+    url.searchParams.append(key, String(value));
+  }
+
+  Object.entries(query).forEach(([key, value]) => {
+    appendQueryValue(key, value);
   });
 
   return url.toString();
@@ -382,6 +410,7 @@ module.exports = {
   fetchWhoAmI,
   getValidAccessToken,
   __private: {
+    buildUrlWithQuery,
     parseTrustedApiUrl,
   },
 };