not-manage 0.1.18 → 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.1.18",
+  "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

@@ -0,0 +1,472 @@
+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(/^--/, "");
+}
+
+function toSnakeCase(name) {
+  return normalizeOptionName(name).replace(/-/g, "_");
+}
+
+function toKebabCase(name) {
+  return normalizeOptionName(name).replace(/_/g, "-");
+}
+
+function optionKeyCandidates(name) {
+  const normalized = normalizeOptionName(name);
+  return [...new Set([normalized, toKebabCase(normalized), toSnakeCase(normalized)])];
+}
+
+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 = [];
+
+  for (let index = 0; index < args.length; index += 1) {
+    const token = args[index];
+
+    if (!token.startsWith("--")) {
+      positional.push(token);
+      continue;
+    }
+
+    const [rawKey, ...rest] = token.slice(2).split("=");
+    const inlineValue = rest.length > 0 ? rest.join("=") : null;
+
+    if (inlineValue !== null) {
+      appendParsedValue(parsed, rawKey, inlineValue);
+      continue;
+    }
+
+    const next = args[index + 1];
+    if (next && !next.startsWith("--")) {
+      appendParsedValue(parsed, rawKey, next);
+      index += 1;
+      continue;
+    }
+
+    appendParsedValue(parsed, rawKey, true);
+  }
+
+  return { parsed, positional };
+}
+
+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 values[values.length - 1];
+}
+
+function readStringOption(parsedOptions, name) {
+  const value = readLastOptionValue(parsedOptions, name);
+  if (value === undefined) {
+    return undefined;
+  }
+
+  if (value === true) {
+    throw new Error(`\`--${toKebabCase(name)}\` requires a value.`);
+  }
+
+  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;
+  }
+
+  if (typeof value === "string") {
+    const normalized = value.trim().toLowerCase();
+    if (normalized === "true") {
+      return true;
+    }
+    if (normalized === "false") {
+      return false;
+    }
+  }
+
+  throw new Error(`\`--${toKebabCase(name)}\` must be \`true\` or \`false\`.`);
+}
+
+function readBooleanOption(parsedOptions, name) {
+  const value = readLastOptionValue(parsedOptions, name);
+  if (value === undefined) {
+    return undefined;
+  }
+
+  return parseBooleanValue(value, name);
+}
+
+function readFlagOption(parsedOptions, name) {
+  const value = readBooleanOption(parsedOptions, name);
+  return value === undefined ? false : value;
+}
+
+function validateIsoDate(value, name) {
+  const match = /^(\d{4})-(\d{2})-(\d{2})$/.exec(value);
+  if (!match) {
+    throw new Error(`\`--${toKebabCase(name)}\` must be an ISO date like \`2026-03-13\`.`);
+  }
+
+  const isoValue = `${match[1]}-${match[2]}-${match[3]}`;
+  const parsed = new Date(`${isoValue}T00:00:00Z`);
+  if (Number.isNaN(parsed.getTime()) || parsed.toISOString().slice(0, 10) !== isoValue) {
+    throw new Error(`\`--${toKebabCase(name)}\` must be an ISO date like \`2026-03-13\`.`);
+  }
+
+  return value;
+}
+
+function validateIsoDateTime(value, name) {
+  const isoDateTime =
+    /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}(?::\d{2}(?:\.\d{1,3})?)?(?:Z|[+-]\d{2}:\d{2})$/;
+  if (!isoDateTime.test(value) || Number.isNaN(Date.parse(value))) {
+    throw new Error(
+      `\`--${toKebabCase(name)}\` must be an ISO datetime like \`2026-03-13T15:00:00Z\`.`
+    );
+  }
+
+  return value;
+}
+
+function readIsoDateOption(parsedOptions, name) {
+  const value = readStringOption(parsedOptions, name);
+  if (value === undefined) {
+    return undefined;
+  }
+
+  return validateIsoDate(value, name);
+}
+
+function readIsoDateTimeOption(parsedOptions, name) {
+  const value = readStringOption(parsedOptions, name);
+  if (value === undefined) {
+    return undefined;
+  }
+
+  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 };
+
+  Object.entries(schema || {}).forEach(([propertyName, optionDef]) => {
+    if (optionDef.positional !== undefined) {
+      options[propertyName] = positional[optionDef.positional];
+      return;
+    }
+
+    switch (optionDef.kind) {
+      case "boolean":
+        options[propertyName] = readBooleanOption(parsedOptions, optionDef.option);
+        return;
+      case "flag":
+        options[propertyName] = readFlagOption(parsedOptions, optionDef.option);
+        return;
+      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);
+    }
+  });
+
+  return {
+    ...options,
+    ...fixed,
+  };
+}
+
+module.exports = {
+  hasFlag,
+  parseOptions,
+  readBooleanOption,
+  readCommandOptions,
+  readFlagOption,
+  readIsoDateOption,
+  readIsoDateArrayOption,
+  readIsoDateTimeOption,
+  readIsoDateTimeArrayOption,
+  readObjectOption,
+  readOption,
+  readOptionValues,
+  readStringOption,
+  readStringArrayOption,
+  toKebabCase,
+};