@wavyx/pdcli 0.7.0 → 0.9.0

package/src/commands/metrics/coverage.js

@@ -0,0 +1,251 @@
+import { Flags } from '@oclif/core'
+import BaseCommand from '../../base-command.js'
+import { collectPages } from '../../lib/pagination.js'
+import { parsePeriod } from '../../lib/period.js'
+import { computeHealth, computeCoverage } from '../../lib/analytics.js'
+import { CliError } from '../../lib/errors.js'
+
+/** YYYY-MM-DD — the date format the Goals API period params expect. */
+function toGoalDate(date) {
+  return date.toISOString().slice(0, 10)
+}
+
+/** Normalize a goal type name for comparison: lowercased, spaces→underscores. */
+function normalizeGoalType(name) {
+  return String(name ?? '')
+    .toLowerCase()
+    .replace(/\s+/g, '_')
+}
+
+/**
+ * Known non-revenue goal type names. A `sum` tracking metric on one of these
+ * (e.g. a deals_won value goal) must not silently join the revenue quota.
+ */
+const NON_REVENUE_TYPES = new Set([
+  'deals_won',
+  'deals_progressed',
+  'deals_started',
+  'activities_completed',
+  'activities_added',
+])
+
+export default class MetricsCoverageCommand extends BaseCommand {
+  static description =
+    'Pipeline coverage: probability-weighted open pipeline vs the revenue still needed to hit quota'
+
+  static examples = [
+    '<%= config.bin %> metrics coverage',
+    '<%= config.bin %> metrics coverage --pipeline 1',
+    '<%= config.bin %> metrics coverage --target 250000',
+    '<%= config.bin %> metrics coverage --period 1m --output json',
+  ]
+
+  static flags = {
+    ...BaseCommand.baseFlags,
+    pipeline: Flags.integer({
+      description: 'Pipeline ID (required when the account has several)',
+    }),
+    period: Flags.string({
+      description: 'Goal measurement window (Nd or Nm)',
+      default: '90d',
+    }),
+    target: Flags.integer({
+      description:
+        'Manual revenue quota override (skips the Goals API entirely)',
+    }),
+  }
+
+  async run() {
+    const { flags } = await this.parse(MetricsCoverageCommand)
+    const now = new Date()
+
+    const pipelineId = await this.#resolvePipeline(flags.pipeline)
+
+    const [stages, open] = await Promise.all([
+      collectPages(
+        this.apiClient.pageV2('/api/v2/stages', {
+          pipeline_id: pipelineId,
+          limit: 500,
+        }),
+      ),
+      collectPages(
+        this.apiClient.pageV2('/api/v2/deals', {
+          pipeline_id: pipelineId,
+          status: 'open',
+          limit: 500,
+        }),
+      ),
+    ])
+
+    // computeHealth gives both the raw open value (classic coverage input)
+    // and the probability-weighted value (risk-adjusted secondary view).
+    // Activities are irrelevant here, so pass an empty list.
+    const healthRows = computeHealth(open, stages, [], { now })
+    const openValue = healthRows.reduce((sum, row) => sum + row.openValue, 0)
+    const weightedOpen = healthRows.reduce(
+      (sum, row) => sum + row.weightedValue,
+      0,
+    )
+
+    const { goalTarget, progress } =
+      flags.target != null
+        ? { goalTarget: flags.target, progress: 0 }
+        : await this.#fetchRevenueGoal(flags.period, now)
+
+    const coverage = computeCoverage({
+      openValue,
+      weightedOpen,
+      goalTarget,
+      progress,
+    })
+
+    if (this.resolveFormat() === 'table') {
+      await this.#renderTable(coverage)
+      return
+    }
+
+    await this.outputResults(coverage, {})
+  }
+
+  /**
+   * Resolve the pipeline to report on: the explicit flag, else the only
+   * pipeline in the account. Several pipelines without a flag is a usage error.
+   * @param {number | undefined} flagPipeline
+   */
+  async #resolvePipeline(flagPipeline) {
+    if (flagPipeline != null) return flagPipeline
+
+    const body = await this.apiClient.get('/api/v2/pipelines')
+    const pipelines = body.data ?? []
+    if (pipelines.length > 1) {
+      throw new CliError(
+        `Account has ${pipelines.length} pipelines — pass --pipeline <id> ` +
+          `(${pipelines.map((p) => `${p.id}=${p.name}`).join(', ')})`,
+        { exitCode: 64 },
+      )
+    }
+    return pipelines[0]?.id
+  }
+
+  /**
+   * Find the active revenue goal(s) via the v1 Goals API and read their
+   * progress. The find enum has no `revenue_forecast`, so query without a
+   * type and filter client-side. Prefer goals whose type normalizes to
+   * `revenue_forecast`; otherwise fall back to `sum` goals that are not a
+   * known non-revenue type (so a deals_won sum goal does not silently join
+   * the quota). A lone non-revenue sum goal is used as a last resort with a
+   * stderr note. Targets/progress are summed across matched goals, which must
+   * share a single currency.
+   * @param {string} period
+   * @param {Date} now
+   */
+  async #fetchRevenueGoal(period, now) {
+    const periodStart = toGoalDate(parsePeriod(period, now))
+    const periodEnd = toGoalDate(now)
+
+    const found = await this.apiClient.get('/api/v1/goals/find', {
+      query: { 'period.start': periodStart, 'period.end': periodEnd },
+    })
+
+    const allGoals = found.data?.goals ?? []
+
+    // True revenue goals: type name normalizes to revenue_forecast.
+    const revenueGoals = allGoals.filter(
+      (g) => normalizeGoalType(g.type?.name) === 'revenue_forecast',
+    )
+    // Fallback: value (`sum`) goals whose type is NOT a known non-revenue type.
+    // A deals_won sum goal must not silently join the revenue quota.
+    const fallbackGoals = allGoals.filter(
+      (g) =>
+        g.expected_outcome?.tracking_metric === 'sum' &&
+        normalizeGoalType(g.type?.name) !== 'revenue_forecast' &&
+        !NON_REVENUE_TYPES.has(normalizeGoalType(g.type?.name)),
+    )
+
+    let goals = revenueGoals.length > 0 ? revenueGoals : fallbackGoals
+
+    // If nothing matched even loosely, fall back to any sum goal so a lone
+    // deals_won value goal can still serve as the quota — but flag what we used.
+    if (goals.length === 0) {
+      const sumGoals = allGoals.filter(
+        (g) => g.expected_outcome?.tracking_metric === 'sum',
+      )
+      if (sumGoals.length > 0) {
+        const types = [
+          ...new Set(sumGoals.map((g) => normalizeGoalType(g.type?.name))),
+        ].join(', ')
+        process.stderr.write(
+          `Note: no revenue_forecast goal found; using sum goal(s) of type ` +
+            `'${types}' as the quota.\n`,
+        )
+        goals = sumGoals
+      }
+    }
+
+    if (goals.length === 0) {
+      throw new CliError(
+        'No active revenue goal found — create one in Pipedrive or pass --target',
+        { exitCode: 64 },
+      )
+    }
+
+    // Coverage cannot sum targets/progress across mixed currencies.
+    // A goal without a currency_id is its own bucket — mixing it with a
+    // real currency is just as unsumable as mixing two real ones.
+    const currencyIds = [
+      ...new Set(goals.map((g) => g.expected_outcome?.currency_id ?? 'none')),
+    ]
+    if (currencyIds.length > 1) {
+      throw new CliError(
+        `Goals use multiple currencies (ids: ${currencyIds.join(', ')}) — ` +
+          `coverage cannot mix them; pass --target to set a single quota.`,
+        { exitCode: 64 },
+      )
+    }
+
+    const goalTarget = goals.reduce(
+      (sum, g) => sum + (g.expected_outcome?.target ?? 0),
+      0,
+    )
+
+    const results = await Promise.all(
+      goals.map((g) =>
+        this.apiClient.get(`/api/v1/goals/${g.id}/results`, {
+          query: { 'period.start': periodStart, 'period.end': periodEnd },
+        }),
+      ),
+    )
+    const progress = results.reduce(
+      (sum, r) => sum + (r.data?.progress ?? 0),
+      0,
+    )
+
+    return { goalTarget, progress }
+  }
+
+  /** @param {ReturnType<typeof computeCoverage>} coverage */
+  async #renderTable(coverage) {
+    const money = (n) => String(Math.round(n))
+    const ratio =
+      coverage.coverage == null ? 'covered' : `${coverage.coverage.toFixed(1)}x`
+
+    const weightedRatio =
+      coverage.weightedCoverage == null
+        ? 'covered'
+        : `${coverage.weightedCoverage.toFixed(1)}x`
+
+    await this.outputResults(
+      [
+        { metric: 'Open pipeline', value: money(coverage.openValue) },
+        { metric: 'Weighted pipeline', value: money(coverage.weightedOpen) },
+        { metric: 'Quota', value: money(coverage.goalTarget) },
+        { metric: 'Progress', value: money(coverage.progress) },
+        { metric: 'Remaining', value: money(coverage.remaining) },
+        { metric: 'Coverage ratio', value: ratio },
+        { metric: 'Weighted coverage', value: weightedRatio },
+        { metric: 'Verdict', value: coverage.verdict },
+      ],
+      { metric: { header: 'Metric' }, value: { header: 'Value' } },
+    )
+  }
+}

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/org/merge.js

@@ -0,0 +1,97 @@
+import { Args, Flags } from '@oclif/core'
+import BaseCommand from '../../base-command.js'
+import { confirmAction } from '../../lib/confirm.js'
+import { CliError, ApiError } from '../../lib/errors.js'
+import { outputRecord } from '../../lib/entity-view.js'
+
+export default class OrgMergeCommand extends BaseCommand {
+  static description =
+    'Merge one organization into another. WARNING: the positional <id> is ' +
+    'the LOSING record — Pipedrive deletes it. --into is the surviving ' +
+    'record whose data wins on conflict. All related data (deals, ' +
+    'activities, notes, files) is transferred to the survivor.'
+
+  static examples = [
+    '<%= config.bin %> org merge 123 --into 456',
+    '<%= config.bin %> org merge 123 --into 456 --yes',
+  ]
+
+  static args = {
+    id: Args.integer({
+      required: true,
+      description: 'ID of the organization to merge and DELETE (the loser)',
+    }),
+  }
+
+  static flags = {
+    ...BaseCommand.baseFlags,
+    into: Flags.integer({
+      required: true,
+      description: 'ID of the surviving organization to keep (the winner)',
+    }),
+    yes: Flags.boolean({
+      char: 'y',
+      description: 'Skip the confirmation prompt',
+      default: false,
+    }),
+  }
+
+  async run() {
+    const { args, flags } = await this.parse(OrgMergeCommand)
+
+    if (args.id === flags.into) {
+      throw new CliError('Cannot merge an organization into itself', {
+        exitCode: 64,
+      })
+    }
+
+    // Unless --yes, look up BOTH records first so the prompt can name them and
+    // a bad id hard-fails BEFORE the irreversible merge. With --yes we skip the
+    // lookups and the prompt entirely to save rate-limit budget.
+    if (!flags.yes) {
+      const loser = await this.apiClient.get(`/api/v2/organizations/${args.id}`)
+      const winner = await this.apiClient.get(
+        `/api/v2/organizations/${flags.into}`,
+      )
+
+      const ok = await confirmAction(
+        `Merge organization ${args.id} "${loser.data?.name}" into ` +
+          `${flags.into} "${winner.data?.name}"? ` +
+          `Organization ${args.id} "${loser.data?.name}" will be DELETED.`,
+        false,
+        { default: false },
+      )
+      if (!ok) {
+        throw new CliError('Aborted', { exitCode: 1 })
+      }
+    }
+
+    // The v1 merge response only carries { id }; re-fetch the full survivor
+    // from v2 so output matches `org get`.
+    const merge = await this.apiClient.put(
+      `/api/v1/organizations/${args.id}/merge`,
+      { body: { merge_with_id: flags.into } },
+    )
+
+    this.logToStderr(`Merged organization ${args.id} into ${flags.into}`)
+
+    let record
+    try {
+      const body = await this.apiClient.get(
+        `/api/v2/organizations/${flags.into}`,
+      )
+      record = body.data
+    } catch (err) {
+      // Only API-level failures (eventual-consistency 404, transient 5xx)
+      // degrade gracefully — anything else is a real bug and must surface.
+      if (!(err instanceof ApiError)) throw err
+      // The merge already succeeded and is irreversible; an eventual-consistency
+      // 404 or transient 500 on the re-fetch must not look like a failure, or an
+      // agent would retry the destructive op. Warn and emit the minimal id.
+      this.logToStderr('Warning: merged, but could not load the survivor view')
+      record = { id: merge.data?.id ?? flags.into }
+    }
+
+    await outputRecord(this, record, '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/person/merge.js

@@ -0,0 +1,91 @@
+import { Args, Flags } from '@oclif/core'
+import BaseCommand from '../../base-command.js'
+import { confirmAction } from '../../lib/confirm.js'
+import { CliError, ApiError } from '../../lib/errors.js'
+import { outputRecord } from '../../lib/entity-view.js'
+
+export default class PersonMergeCommand extends BaseCommand {
+  static description =
+    'Merge one person into another. WARNING: the positional <id> is the ' +
+    'LOSING record — Pipedrive deletes it. --into is the surviving record ' +
+    'whose data wins on conflict. All related data (deals, activities, ' +
+    'notes, files) is transferred to the survivor.'
+
+  static examples = [
+    '<%= config.bin %> person merge 123 --into 456',
+    '<%= config.bin %> person merge 123 --into 456 --yes',
+  ]
+
+  static args = {
+    id: Args.integer({
+      required: true,
+      description: 'ID of the person to merge and DELETE (the loser)',
+    }),
+  }
+
+  static flags = {
+    ...BaseCommand.baseFlags,
+    into: Flags.integer({
+      required: true,
+      description: 'ID of the surviving person to keep (the winner)',
+    }),
+    yes: Flags.boolean({
+      char: 'y',
+      description: 'Skip the confirmation prompt',
+      default: false,
+    }),
+  }
+
+  async run() {
+    const { args, flags } = await this.parse(PersonMergeCommand)
+
+    if (args.id === flags.into) {
+      throw new CliError('Cannot merge a person into itself', { exitCode: 64 })
+    }
+
+    // Unless --yes, look up BOTH records first so the prompt can name them and
+    // a bad id hard-fails BEFORE the irreversible merge. With --yes we skip the
+    // lookups and the prompt entirely to save rate-limit budget.
+    if (!flags.yes) {
+      const loser = await this.apiClient.get(`/api/v2/persons/${args.id}`)
+      const winner = await this.apiClient.get(`/api/v2/persons/${flags.into}`)
+
+      const ok = await confirmAction(
+        `Merge person ${args.id} "${loser.data?.name}" into ` +
+          `${flags.into} "${winner.data?.name}"? ` +
+          `Person ${args.id} "${loser.data?.name}" will be DELETED.`,
+        false,
+        { default: false },
+      )
+      if (!ok) {
+        throw new CliError('Aborted', { exitCode: 1 })
+      }
+    }
+
+    // The v1 merge response carries the raw v1 shape (top-level hash custom
+    // fields, email/phone arrays). Re-fetch the survivor from v2 so output
+    // matches `person get`.
+    const merge = await this.apiClient.put(`/api/v1/persons/${args.id}/merge`, {
+      body: { merge_with_id: flags.into },
+    })
+
+    this.logToStderr(`Merged person ${args.id} into ${flags.into}`)
+
+    let record
+    try {
+      const body = await this.apiClient.get(`/api/v2/persons/${flags.into}`)
+      record = body.data
+    } catch (err) {
+      // Only API-level failures (eventual-consistency 404, transient 5xx)
+      // degrade gracefully — anything else is a real bug and must surface.
+      if (!(err instanceof ApiError)) throw err
+      // The merge already succeeded and is irreversible; an eventual-consistency
+      // 404 or transient 500 on the re-fetch must not look like a failure, or an
+      // agent would retry the destructive op. Warn and emit the minimal id.
+      this.logToStderr('Warning: merged, but could not load the survivor view')
+      record = { id: merge.data?.id ?? flags.into }
+    }
+
+    await outputRecord(this, record, '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/hooks/command-not-found.js

@@ -1,9 +1,74 @@
 import createDebug from 'debug'
 import chalk from 'chalk'
+import { getAlias } from '../lib/aliases.js'
 
 const debug = createDebug('pd:command-not-found')
 
+const MAX_ALIAS_DEPTH = 10
+
+// Tracks alias names expanded within a single process. The hook re-enters
+// itself through oclif's runCommand dispatcher (same module instance), so a
+// module-level Set survives across those re-entrant invocations and lets us
+// detect cycles before they exhaust the stack/heap. Cleared by the root
+// invocation in `finally` so distinct alias runs in one process (e.g. tests,
+// or a long-lived embedding) don't false-positive against each other.
+const aliasChain = new Set()
+
 export default async function commandNotFound(options) {
+  const alias = getAlias(options.id)
+
+  if (alias) {
+    // Runaway detection. Two distinct failure modes, reported distinctly:
+    // a repeated alias name is a true cycle; a long acyclic chain trips the
+    // depth cap (legal but almost certainly a mistake — and the cap is what
+    // keeps a missed cycle from exhausting the heap).
+    if (aliasChain.has(options.id)) {
+      const cycle = [...aliasChain, options.id].join(' -> ')
+      aliasChain.clear()
+      process.stderr.write(
+        `${chalk.red('Error:')} alias cycle detected: ${chalk.yellow(cycle)}\n`,
+      )
+      process.exit(64)
+    }
+    if (aliasChain.size >= MAX_ALIAS_DEPTH) {
+      const chain = [...aliasChain, options.id].join(' -> ')
+      aliasChain.clear()
+      process.stderr.write(
+        `${chalk.red('Error:')} alias expansion exceeded ${MAX_ALIAS_DEPTH} hops: ${chalk.yellow(chain)}\n`,
+      )
+      process.exit(64)
+    }
+
+    // This invocation owns cleanup only if it started a fresh chain.
+    const isRoot = aliasChain.size === 0
+    aliasChain.add(options.id)
+
+    debug('expanding alias %s -> %s', options.id, alias)
+    const aliasArgv = alias.split(/\s+/).filter(Boolean)
+    const fullArgv = [...aliasArgv, ...(options.argv ?? [])]
+
+    let commandId = fullArgv[0]
+    let restArgv = fullArgv.slice(1)
+
+    for (let i = 1; i < fullArgv.length; i++) {
+      const candidate = fullArgv.slice(0, i + 1).join(':')
+      if (options.config.findCommand(candidate)) {
+        commandId = candidate
+        restArgv = fullArgv.slice(i + 1)
+      }
+    }
+
+    try {
+      await options.config.runCommand(commandId, restArgv)
+      process.exit(0)
+    } catch (err) {
+      debug('alias execution failed: %s', err.message)
+      process.exit(err.exitCode ?? 1)
+    } finally {
+      if (isRoot) aliasChain.clear()
+    }
+  }
+
   debug('command not found: %s', options.id)
   process.stderr.write(
     `${chalk.red('Error:')} ${chalk.yellow(options.id)} is not a pdcli command.\n`,
@@ -11,5 +76,8 @@ export default async function commandNotFound(options) {
   process.stderr.write(
     `Run ${chalk.cyan('pdcli help')} for a list of available commands.\n`,
   )
+  process.stderr.write(
+    `Run ${chalk.cyan('pdcli alias list')} to see configured aliases.\n`,
+  )
   process.exit(127)
 }

package/src/lib/aliases.js

@@ -0,0 +1,115 @@
+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') ?? {}
+}
+
+/**
+ * @param {string} name
+ * @returns {string | undefined}
+ */
+export function getAlias(name) {
+  return getAliases()[name]
+}
+
+/**
+ * Write the whole `aliases` object back with a literal key, rather than a
+ * 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) {
+  withAliasLock(() => {
+    const aliases = { ...getAliases(), [name]: command }
+    getConf().set('aliases', aliases)
+  })
+}
+
+/**
+ * @param {string} name
+ */
+export function unsetAlias(name) {
+  withAliasLock(() => {
+    const aliases = { ...getAliases() }
+    delete aliases[name]
+    getConf().set('aliases', aliases)
+  })
+}