@wavyx/pdcli 0.8.0 → 0.9.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wavyx/pdcli",
-  "version": "0.8.0",
+  "version": "0.9.0",
   "publishConfig": {
     "access": "public"
   },

package/src/base-command.js

@@ -24,7 +24,7 @@ export default class BaseCommand extends Command {
     }),
     'resolve-fields': Flags.boolean({
       description:
-        'Resolve custom-field hash keys to names (and option ids to labels) in json/yaml/csv output of single-record get commands',
+        'Resolve custom-field hash keys to names (and option ids to labels) in json/yaml/csv output of get and core list commands',
       helpGroup: 'GLOBAL',
       default: false,
     }),
@@ -151,12 +151,31 @@ export default class BaseCommand extends Command {
   /**
    * @param {object | object[]} data
    * @param {Record<string, import('./lib/output/table.js').Column>} columns
+   * @param {{ entity?: string }} [options] entity context enables
+   *   --resolve-fields custom-field resolution on machine-format lists
    */
-  async outputResults(data, columns) {
+  async outputResults(data, columns, { entity } = {}) {
+    if (
+      entity &&
+      this.flags['resolve-fields'] &&
+      this.resolveFormat() !== 'table' &&
+      Array.isArray(data) &&
+      data.some((row) => row?.custom_fields)
+    ) {
+      const { getFields, makeResolver } = await import('./lib/fields.js')
+      // getFields is memoized per run — one defs fetch covers the whole list.
+      const resolver = makeResolver(await getFields(this.apiClient, entity))
+      data = data.map((row) =>
+        row?.custom_fields ? resolver.resolveCustomFields(row) : row,
+      )
+    }
+
     if (this.flags.jq) {
       // node-jq ships a native binary — load it only when actually used.
+      // Single records pass UNWRAPPED: `--jq .id` works on a get without
+      // the historical `.[0]` indirection (changed in 0.9.0).
       const { run } = await import('node-jq')
-      const input = JSON.stringify(Array.isArray(data) ? data : [data])
+      const input = JSON.stringify(data)
       const result = await run(this.flags.jq, input, {
         input: 'string',
         output: 'pretty',

package/src/commands/activity/list.js

@@ -56,6 +56,6 @@ export default class ActivityListCommand extends BaseCommand {
       this.apiClient.pageV2('/api/v2/activities', query),
       limit,
     )
-    await this.outputResults(items, columns)
+    await this.outputResults(items, columns, { entity: 'activity' })
   }
 }

package/src/commands/deal/list.js

@@ -57,6 +57,6 @@ export default class DealListCommand extends BaseCommand {
       this.apiClient.pageV2('/api/v2/deals', query),
       limit,
     )
-    await this.outputResults(items, columns)
+    await this.outputResults(items, columns, { entity: 'deal' })
   }
 }

package/src/commands/org/list.js

@@ -35,6 +35,6 @@ export default class OrgListCommand extends BaseCommand {
       this.apiClient.pageV2('/api/v2/organizations', query),
       limit,
     )
-    await this.outputResults(items, columns)
+    await this.outputResults(items, columns, { entity: 'org' })
   }
 }

package/src/commands/person/list.js

@@ -44,6 +44,6 @@ export default class PersonListCommand extends BaseCommand {
       this.apiClient.pageV2('/api/v2/persons', query),
       limit,
     )
-    await this.outputResults(items, columns)
+    await this.outputResults(items, columns, { entity: 'person' })
   }
 }

package/src/commands/product/list.js

@@ -40,6 +40,6 @@ export default class ProductListCommand extends BaseCommand {
       this.apiClient.pageV2('/api/v2/products', query),
       limit,
     )
-    await this.outputResults(items, columns)
+    await this.outputResults(items, columns, { entity: 'product' })
   }
 }

package/src/lib/aliases.js

@@ -1,4 +1,78 @@
+import fs from 'node:fs'
 import { getConf } from './config.js'
+import { CliError } from './errors.js'
+
+const LOCK_STALE_MS = 5000
+const LOCK_RETRIES = 8
+const LOCK_RETRY_MS = 50
+
+/** Synchronous sleep for the short lock-retry loop (no event-loop yield needed). */
+function sleepSync(ms) {
+  Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms)
+}
+
+/**
+ * Release the lock. Never throws: the mutation already persisted, so a
+ * failed release must not convert success into a reported failure (a
+ * leftover dir goes stale in 5s and is reaped by the next writer).
+ */
+function releaseLock(lockDir) {
+  try {
+    fs.rmdirSync(lockDir)
+  } catch {
+    /* benign: stale-broken concurrently, or unremovable — reaped later */
+  }
+}
+
+/**
+ * Advisory lock around alias mutations: a lock DIRECTORY next to the conf
+ * file (mkdir is atomic on every platform we support). Protects concurrent
+ * pdcli processes from clobbering each other's read-modify-write of the
+ * aliases object — advisory only; other writers aren't covered. A lock left
+ * behind by a crashed process goes stale after 5s and is broken.
+ * @param {() => void} fn the mutation to run while holding the lock
+ */
+function withAliasLock(fn) {
+  const lockDir = `${getConf().path}.aliases.lock`
+
+  for (let attempt = 0; attempt <= LOCK_RETRIES; attempt++) {
+    try {
+      fs.mkdirSync(lockDir)
+      try {
+        fn()
+        return
+      } finally {
+        releaseLock(lockDir)
+      }
+    } catch (err) {
+      if (err?.code !== 'EEXIST') {
+        // Not contention — the config dir itself is unusable. Name the real
+        // problem instead of leaking the lock implementation detail.
+        throw new CliError(
+          `Cannot update aliases: the config directory is not writable (${err?.code ?? err?.message})`,
+          { exitCode: 78 },
+        )
+      }
+      // Held by someone else — break it if stale, otherwise wait and retry.
+      let stale
+      try {
+        stale = Date.now() - fs.statSync(lockDir).mtimeMs > LOCK_STALE_MS
+      } catch {
+        continue // lock vanished between mkdir and stat — retry immediately
+      }
+      if (stale) {
+        fs.rmdirSync(lockDir) // a real failure here must surface, not retry
+        continue
+      }
+      if (attempt < LOCK_RETRIES) sleepSync(LOCK_RETRY_MS)
+    }
+  }
+
+  throw new CliError(
+    'another pdcli process is updating aliases — retry in a moment',
+    { exitCode: 75 },
+  )
+}
 
 export function getAliases() {
   return getConf().get('aliases') ?? {}
@@ -17,19 +91,25 @@ export function getAlias(name) {
  * dotted-path write. conf splits `set('aliases.<name>', …)` on every '.', so a
  * dotted-path write would corrupt any name containing a dot (store/read
  * mismatch). Mutating the object and writing it whole keeps odd names flat.
+ * The read-modify-write runs under an advisory lock so concurrent pdcli
+ * processes can't clobber each other.
  * @param {string} name
  * @param {string} command
  */
 export function setAlias(name, command) {
-  const aliases = { ...getAliases(), [name]: command }
-  getConf().set('aliases', aliases)
+  withAliasLock(() => {
+    const aliases = { ...getAliases(), [name]: command }
+    getConf().set('aliases', aliases)
+  })
 }
 
 /**
  * @param {string} name
  */
 export function unsetAlias(name) {
-  const aliases = { ...getAliases() }
-  delete aliases[name]
-  getConf().set('aliases', aliases)
+  withAliasLock(() => {
+    const aliases = { ...getAliases() }
+    delete aliases[name]
+    getConf().set('aliases', aliases)
+  })
 }

package/src/lib/client.js

@@ -79,6 +79,87 @@ export function createClient({
       }
     }
 
+    return transport(method, url, {
+      path,
+      makeBody: body ? () => JSON.stringify(body) : undefined,
+      extraHeaders: { 'content-type': 'application/json' },
+    })
+  }
+
+  /**
+   * v2 cursor pagination: cursor/limit → additional_data.next_cursor.
+   * @param {string} path
+   * @param {object} [query]
+   * @returns {AsyncGenerator<object>}
+   */
+  async function* pageV2(path, query = {}) {
+    let cursor
+    const baseQuery = clampLimit(query)
+    while (true) {
+      const envelope = await request('GET', path, {
+        query: cursor ? { ...baseQuery, cursor } : baseQuery,
+      })
+      yield* envelope?.data ?? []
+      cursor = envelope?.additional_data?.next_cursor
+      if (!cursor) break
+    }
+  }
+
+  /**
+   * v1 offset pagination: start/limit →
+   * additional_data.pagination.{more_items_in_collection,next_start}.
+   * @param {string} path
+   * @param {object} [query]
+   * @returns {AsyncGenerator<object>}
+   */
+  async function* pageV1(path, query = {}) {
+    let start
+    const baseQuery = clampLimit(query)
+    while (true) {
+      const envelope = await request('GET', path, {
+        query: start != null ? { ...baseQuery, start } : baseQuery,
+      })
+      yield* envelope?.data ?? []
+      const pagination = envelope?.additional_data?.pagination
+      if (!pagination?.more_items_in_collection) break
+      start = pagination.next_start
+    }
+  }
+
+  function lockedUrl(path) {
+    const url = new URL(path, baseOrigin)
+    if (url.origin !== baseOrigin) {
+      throw new CliError(
+        `Refusing to send request outside your Pipedrive company host ` +
+          `(${baseOrigin}): ${url.origin}`,
+        { exitCode: 78 },
+      )
+    }
+    return url
+  }
+
+  function authHeaders() {
+    return authMode === 'oauth'
+      ? { authorization: `Bearer ${token}`, 'user-agent': userAgent }
+      : { 'x-api-token': token, 'user-agent': userAgent }
+  }
+
+  /**
+   * Shared transport: EVERY HTTP path (JSON, form, multipart, binary) goes
+   * through the same 429 backoff (x-ratelimit-reset → Retry-After → default),
+   * 429→403 escalation hard stop, 5xx retry, OAuth refresh-once, and error
+   * mapping. `makeBody` is invoked per attempt — FormData and friends are
+   * rebuilt rather than reused across retries.
+   * @param {string} method
+   * @param {URL} url
+   * @param {{ path: string, makeBody?: () => any,
+   *   extraHeaders?: Record<string, string>, binary?: boolean }} options
+   */
+  async function transport(
+    method,
+    url,
+    { path, makeBody, extraHeaders = {}, binary = false },
+  ) {
     const maxAttempts = retry ? 3 : 1
     let attempts = 0
     let sawRateLimit = false
@@ -86,20 +167,10 @@ export function createClient({
     while (attempts < maxAttempts) {
       attempts++
 
-      const headers = {
-        'content-type': 'application/json',
-        'user-agent': userAgent,
-      }
-      if (authMode === 'oauth') {
-        headers.authorization = `Bearer ${token}`
-      } else {
-        headers['x-api-token'] = token
-      }
-
       const res = await fetch(url, {
         method,
-        headers,
-        body: body ? JSON.stringify(body) : undefined,
+        headers: { ...authHeaders(), ...extraHeaders },
+        body: makeBody ? makeBody() : undefined,
         signal: AbortSignal.timeout(timeout),
       })
 
@@ -141,97 +212,38 @@ export function createClient({
         continue
       }
 
+      // Binary callers always get the {buffer, contentType} shape — a 204
+      // yields an empty buffer rather than null (pre-unification parity;
+      // file/download destructures the result).
+      if (binary) {
+        if (!res.ok) {
+          throw ApiError.fromResponse(res.status, await res.text(), path)
+        }
+        return {
+          buffer: await res.arrayBuffer(),
+          contentType: res.headers.get('content-type'),
+        }
+      }
+
       if (res.status === 204) return null
 
       const text = await res.text()
-
       if (!res.ok) {
         throw ApiError.fromResponse(res.status, text, path)
       }
-
       return text ? JSON.parse(text) : null
     }
 
     throw new ServiceUnavailableError()
   }
 
-  /**
-   * v2 cursor pagination: cursor/limit → additional_data.next_cursor.
-   * @param {string} path
-   * @param {object} [query]
-   * @returns {AsyncGenerator<object>}
-   */
-  async function* pageV2(path, query = {}) {
-    let cursor
-    const baseQuery = clampLimit(query)
-    while (true) {
-      const envelope = await request('GET', path, {
-        query: cursor ? { ...baseQuery, cursor } : baseQuery,
-      })
-      yield* envelope?.data ?? []
-      cursor = envelope?.additional_data?.next_cursor
-      if (!cursor) break
-    }
-  }
-
-  /**
-   * v1 offset pagination: start/limit →
-   * additional_data.pagination.{more_items_in_collection,next_start}.
-   * @param {string} path
-   * @param {object} [query]
-   * @returns {AsyncGenerator<object>}
-   */
-  async function* pageV1(path, query = {}) {
-    let start
-    const baseQuery = clampLimit(query)
-    while (true) {
-      const envelope = await request('GET', path, {
-        query: start != null ? { ...baseQuery, start } : baseQuery,
-      })
-      yield* envelope?.data ?? []
-      const pagination = envelope?.additional_data?.pagination
-      if (!pagination?.more_items_in_collection) break
-      start = pagination.next_start
-    }
-  }
-
-  function lockedUrl(path) {
-    const url = new URL(path, baseOrigin)
-    if (url.origin !== baseOrigin) {
-      throw new CliError(
-        `Refusing to send request outside your Pipedrive company host ` +
-          `(${baseOrigin}): ${url.origin}`,
-        { exitCode: 78 },
-      )
-    }
-    return url
-  }
-
-  function authHeaders() {
-    return authMode === 'oauth'
-      ? { authorization: `Bearer ${token}`, 'user-agent': userAgent }
-      : { 'x-api-token': token, 'user-agent': userAgent }
-  }
-
   /**
    * Download a binary resource (e.g. /api/v1/files/:id/download).
    * @param {string} path
    * @returns {Promise<{buffer: ArrayBuffer, contentType: string | null}>}
    */
   async function download(path) {
-    const url = lockedUrl(path)
-    const res = await fetch(url, {
-      headers: authHeaders(),
-      signal: AbortSignal.timeout(timeout),
-    })
-    debug('GET (binary) %s → %d', path, res.status)
-    if (!res.ok) {
-      throw ApiError.fromResponse(res.status, await res.text(), path)
-    }
-    return {
-      buffer: await res.arrayBuffer(),
-      contentType: res.headers.get('content-type'),
-    }
+    return transport('GET', lockedUrl(path), { path, binary: true })
   }
 
   /**
@@ -240,24 +252,16 @@ export function createClient({
    * @param {{ file: { name: string, data: Buffer | Uint8Array }, fields?: Record<string, unknown> }} options
    */
   async function postMultipart(path, { file, fields = {} }) {
-    const url = lockedUrl(path)
-    const form = new FormData()
-    form.set('file', new Blob([file.data]), file.name)
-    for (const [k, v] of Object.entries(fields)) {
-      if (v != null) form.set(k, String(v))
-    }
-    const res = await fetch(url, {
-      method: 'POST',
-      headers: authHeaders(), // fetch sets the multipart boundary itself
-      body: form,
-      signal: AbortSignal.timeout(timeout),
-    })
-    debug('POST (multipart) %s → %d', path, res.status)
-    const text = await res.text()
-    if (!res.ok) {
-      throw ApiError.fromResponse(res.status, text, path)
+    // fetch sets the multipart boundary itself — no content-type override.
+    const makeBody = () => {
+      const form = new FormData()
+      form.set('file', new Blob([file.data]), file.name)
+      for (const [k, v] of Object.entries(fields)) {
+        if (v != null) form.set(k, String(v))
+      }
+      return form
     }
-    return text ? JSON.parse(text) : null
+    return transport('POST', lockedUrl(path), { path, makeBody })
   }
 
   /**
@@ -267,26 +271,15 @@ export function createClient({
    * @param {Record<string, unknown>} fields Null/undefined values are omitted.
    */
   async function postForm(path, fields = {}) {
-    const url = lockedUrl(path)
     const params = new URLSearchParams()
     for (const [k, v] of Object.entries(fields)) {
       if (v != null) params.set(k, String(v))
     }
-    const res = await fetch(url, {
-      method: 'POST',
-      headers: {
-        ...authHeaders(),
-        'content-type': 'application/x-www-form-urlencoded',
-      },
-      body: params.toString(),
-      signal: AbortSignal.timeout(timeout),
+    return transport('POST', lockedUrl(path), {
+      path,
+      makeBody: () => params.toString(),
+      extraHeaders: { 'content-type': 'application/x-www-form-urlencoded' },
     })
-    debug('POST (form) %s → %d', path, res.status)
-    const text = await res.text()
-    if (!res.ok) {
-      throw ApiError.fromResponse(res.status, text, path)
-    }
-    return text ? JSON.parse(text) : null
   }
 
   return {