fg-devkit 1.17.3 → 1.19.2

package/scripts/piwik.mjs

@@ -0,0 +1,502 @@
+#!/usr/bin/env node
+/**
+ * Maintainer tool for Piwik PRO custom dimensions.
+ *
+ * Reads the consumer's local slot map (src/analytics/dimensions.ts or
+ * src/util/piwikDimensions.ts) and compares it with the site in Piwik.
+ * Session and event dimensions are created one at a time, and only when the
+ * next free slot in that scope is the local slot. Product dimensions send the
+ * local slot (1–20). There is no delete: deactivating a dimension does not
+ * free its slot.
+ *
+ *   pnpm exec fg-devkit piwik list [--local] [--env preprod] [--scope event]
+ *   pnpm exec fg-devkit piwik diff
+ *   pnpm exec fg-devkit piwik add [--yes] [--dry-run]
+ *   pnpm exec fg-devkit piwik update [--yes] [--dry-run]
+ *   pnpm exec fg-devkit piwik sync [--yes] [--dry-run]
+ *   pnpm exec fg-devkit piwik pull [--env preprod] [--yes] [--dry-run]
+ *   pnpm exec fg-devkit piwik compare [--from preprod] [--to production]
+ *   pnpm exec fg-devkit piwik migrate [--from preprod] [--to production] [--yes] [--dry-run]
+ *
+ * Credentials: PIWIK_CLIENT_ID and PIWIK_CLIENT_SECRET (env, .env.local, or env.local).
+ * Site: --account / --website-id, piwik/.piwik.json, or src/config/env.ts.
+ * Optional piwik/.piwik.json names override the Piwik label for a local key.
+ */
+
+import fs from 'node:fs'
+
+import {
+  PiwikDimensionError,
+  SCOPES,
+  diffDimensions,
+  diffEnvironments,
+  formatDimensionReport,
+  formatEnvironmentReport,
+  planCreates,
+  planEnvironmentMigration,
+  planLocalPull,
+  renderTable,
+  rewriteDimensionNumbers,
+} from './piwik-dimensions.mjs'
+import {
+  assertApiConfig,
+  createPiwikClient,
+  loadLocalDimensions,
+  resolveEnvironmentPair,
+  resolvePiwikConfig,
+} from './piwik-common.mjs'
+
+const COMMANDS = new Set(['list', 'diff', 'add', 'update', 'sync', 'pull', 'compare', 'migrate'])
+
+function printHelp() {
+  console.log(`Usage:
+  pnpm exec fg-devkit piwik <command> [options]
+
+Commands:
+  list     List dimensions in Piwik. --local prints the repo map and skips the API.
+  diff     Compare the local slot map with Piwik. Exits 1 when they differ.
+  add      Create local dimensions that are missing in Piwik, in slot order.
+  update   Rename Piwik dimensions whose name differs from the local key.
+  sync     Copy the local map up to Piwik: add missing dimensions, then rename. Does not edit the repo.
+  pull     Copy tracking ids from Piwik down into the local map for keys with the same name.
+  compare  Compare two sites from src/config/env.ts. Exits 1 when they differ.
+  migrate  Copy dimensions from --from onto --to. Creates one at a time and checks tracking_id.
+
+Options:
+  --env <name>           Environment object in src/config/env.ts (default: first non-production site, such as preprod)
+  --from <name>          Source site for compare and migrate (default: first non-production site)
+  --to <name>            Target site for compare and migrate (default: production when that site exists)
+  --account <name>       Piwik account (the subdomain of {account}.piwik.pro)
+  --website-id <uuid>    Site id. Defaults to piwikId / piwikProId for --env
+  --dimensions <file>    Local map. Default: src/analytics/dimensions.ts or src/util/piwikDimensions.ts
+  --config <file>        Optional piwik/.piwik.json (account, websiteId, environment, dimensionsFile, names)
+  --scope <event|session|product>
+  --client-id <id>       Overrides PIWIK_CLIENT_ID
+  --client-secret <secret>
+  --yes                  Apply add, update, or sync. Without this, a TTY asks first and other runs only print the plan.
+  --dry-run              Print the plan and do not call create or update
+  --local                With list: print only the local map
+
+The tracker sends dimension{slot}. Slot and tracking_id are read-only and assigned
+by Piwik for session and event dimensions. A create stops the loop if the returned
+slot is not the local slot.`)
+}
+
+/**
+ * @param {import('./piwik-dimensions.mjs').LocalDimension[]} locals
+ */
+function printLocal(locals) {
+  for (const scope of SCOPES) {
+    const scoped = locals.filter((item) => item.scope === scope).sort((a, b) => a.slot - b.slot)
+    if (scoped.length === 0) continue
+    console.log(`\n${scope}`)
+    console.log(`${'slot'.padEnd(6)}key`)
+    for (const local of scoped) {
+      console.log(`${String(local.slot).padEnd(6)}${local.name}`)
+    }
+  }
+  const counts = SCOPES.map((scope) => `${locals.filter((item) => item.scope === scope).length} ${scope}`).join(', ')
+  console.log(`\n[piwik] ${locals.length} local dimensions (${counts})`)
+}
+
+/**
+ * @param {import('./piwik-dimensions.mjs').RemoteDimension[]} dimensions
+ * @param {Record<string, { used?: number, available?: number, left?: number }>} slots
+ */
+function printRemote(dimensions, slots) {
+  const slotLine = SCOPES.map((scope) => {
+    const stats = slots?.[scope]
+    if (!stats) return `${scope} ?`
+    return `${scope} ${stats.used ?? '?'}/${stats.available ?? '?'} (${stats.left ?? '?'} left)`
+  }).join('  ')
+  console.log(`[piwik] slots  ${slotLine}`)
+  for (const scope of SCOPES) {
+    const scoped = dimensions.filter((item) => item.scope === scope).sort((a, b) => a.slot - b.slot)
+    if (scoped.length === 0) continue
+    console.log(`\n${scope}`)
+    const showDescription = scoped.some((remote) => remote.description.trim() !== '')
+    const headers = ['slot', 'tracking_id', 'state', 'name']
+    if (showDescription) headers.push('description')
+    console.log(
+      renderTable(
+        headers,
+        scoped.map((remote) => {
+          const cells = [String(remote.slot), String(remote.trackingId), remote.active ? 'active' : 'inactive', remote.name]
+          if (showDescription) cells.push(remote.description.trim())
+          return cells
+        }),
+      ).join('\n'),
+    )
+  }
+  console.log(`\n[piwik] ${dimensions.length} dimensions in Piwik`)
+}
+
+/**
+ * @param {string} message
+ * @param {{ yes: boolean, dryRun: boolean }} config
+ */
+async function confirmApply(message, config) {
+  if (config.dryRun) return false
+  if (config.yes) return true
+  if (!process.stdin.isTTY) {
+    console.log('[piwik] Not applied. Re-run with --yes to write to Piwik.')
+    return false
+  }
+  const { default: confirm } = await import('@inquirer/confirm')
+  return confirm({ message, default: false })
+}
+
+/**
+ * @param {ReturnType<typeof createPiwikClient>} client
+ * @param {ReturnType<typeof resolvePiwikConfig>} config
+ * @param {import('./piwik-dimensions.mjs').LocalDimension[]} creates
+ */
+async function applyCreates(client, config, creates) {
+  for (const local of creates) {
+    console.log(`[piwik] creating ${local.scope} ${local.name} dimension${local.slot}`)
+    const created =
+      local.scope === 'product'
+        ? await client.createProductDimension({
+            websiteId: config.websiteId,
+            name: local.name,
+            slot: local.slot,
+          })
+        : await client.createDimension({
+            websiteId: config.websiteId,
+            name: local.name,
+            scope: local.scope,
+          })
+    const assignedId = local.scope === 'product' ? created.slot : created.trackingId
+    if (assignedId !== local.slot) {
+      throw new PiwikDimensionError(
+        `Piwik assigned ${created.scope} slot ${created.slot} (tracking_id ${created.trackingId}) to "${created.name}" (id ${created.id}), but the app sends dimension${local.slot}. Stopped before the next create. Deactivating the dimension does not free the slot.`,
+      )
+    }
+    console.log(`[piwik] created id ${created.id} ${created.scope} slot ${created.slot} tracking_id ${created.trackingId}`)
+  }
+}
+
+/**
+ * @param {ReturnType<typeof createPiwikClient>} client
+ * @param {string} websiteId
+ * @param {{ local: import('./piwik-dimensions.mjs').LocalDimension, remote: import('./piwik-dimensions.mjs').RemoteDimension }[]} updates
+ */
+async function applyUpdates(client, websiteId, updates) {
+  for (const { local, remote } of updates) {
+    const target = remote.websiteId ? remote : { ...remote, websiteId }
+    console.log(`[piwik] updating ${remote.scope} slot ${remote.slot} "${remote.name}" -> "${local.name}"`)
+    const updated =
+      remote.scope === 'product'
+        ? await client.updateProductDimension(target, local.name)
+        : await client.updateDimension(target, local.name)
+    console.log(`[piwik] updated id ${updated.id} name "${updated.name}"`)
+  }
+}
+
+async function main() {
+  const argv = process.argv.slice(2)
+  if (argv.includes('--help') || argv.includes('-h') || argv.length === 0) {
+    printHelp()
+    return argv.length === 0 ? 1 : 0
+  }
+
+  const config = resolvePiwikConfig(argv)
+  if (!COMMANDS.has(config.command)) {
+    console.error(`[piwik] Unknown command: ${config.command}`)
+    printHelp()
+    return 1
+  }
+
+  if (config.command === 'list' && config.localOnly) {
+    printLocal(loadLocalDimensions(config))
+    return 0
+  }
+
+  if (config.command === 'compare' || config.command === 'migrate') {
+    return runEnvironmentCommand(config)
+  }
+
+  if (config.command === 'pull') {
+    return runPull(config)
+  }
+
+  assertApiConfig(config)
+  console.log(
+    `[piwik] account=${config.account} website=${config.websiteId} env=${config.envName}${config.siteSource ? ` (${config.siteSource})` : ''}`,
+  )
+  if (config.dimensionFiles.length > 0 && config.command !== 'list') {
+    console.log(`[piwik] local ${config.dimensionFiles.map((file) => file.replace(`${config.cwd}/`, '')).join(', ')}`)
+  }
+
+  const client = createPiwikClient({
+    account: config.account,
+    clientId: config.clientId,
+    clientSecret: config.clientSecret,
+  })
+  const remoteResult = await client.listDimensions(config.websiteId)
+  const remotes = config.scope
+    ? remoteResult.dimensions.filter((item) => item.scope === config.scope)
+    : remoteResult.dimensions
+  for (const remote of remotes) {
+    if (!remote.websiteId) remote.websiteId = config.websiteId
+  }
+
+  if (config.command === 'list') {
+    printRemote(remotes, remoteResult.slots)
+    return 0
+  }
+
+  const locals = loadLocalDimensions(config)
+  const diff = diffDimensions(locals, remotes)
+  const plan = planCreates(diff.missing, remotes)
+  console.log(formatDimensionReport(diff, plan))
+
+  const wantsCreate = config.command === 'add' || config.command === 'sync'
+  const wantsUpdate = config.command === 'update' || config.command === 'sync'
+  const drifted = diff.missing.length > 0 || diff.remoteOnly.length > 0
+
+  if (config.command === 'diff') return drifted ? 1 : 0
+
+  const createCount = wantsCreate ? plan.creates.length : 0
+  const updateCount = wantsUpdate ? diff.nameMismatch.length : 0
+  if (createCount === 0 && updateCount === 0) {
+    console.log('[piwik] Nothing to write.')
+    return plan.blocked.length > 0 && wantsCreate ? 1 : 0
+  }
+
+  if (config.dryRun) {
+    console.log('[piwik] Dry run. No dimensions were created or updated.')
+    return plan.blocked.length > 0 && wantsCreate ? 1 : 0
+  }
+
+  const apply = await confirmApply(
+    `Copy ${createCount} new and ${updateCount} renamed dimension(s) from the local map up to ${config.envName || config.account}?`,
+    config,
+  )
+  if (!apply) return 0
+
+  /** @type {unknown} */
+  let writeError = null
+  try {
+    if (wantsCreate) await applyCreates(client, config, plan.creates)
+    if (wantsUpdate) await applyUpdates(client, config.websiteId, diff.nameMismatch)
+  } catch (error) {
+    writeError = error
+  }
+
+  console.log('\n[piwik] Piwik after the update:')
+  const refreshed = await listSiteDimensions(client, config.websiteId, config.scope)
+  const nextDiff = diffDimensions(locals, refreshed)
+  const nextPlan = planCreates(nextDiff.missing, refreshed)
+  console.log(formatDimensionReport(nextDiff, nextPlan))
+  if (writeError) throw writeError
+
+  const stillMissing = wantsCreate && (nextPlan.creates.length > 0 || nextPlan.blocked.length > 0)
+  const stillRenamed = wantsUpdate && nextDiff.nameMismatch.length > 0
+  return stillMissing || stillRenamed ? 1 : 0
+}
+
+/**
+ * @param {ReturnType<typeof createPiwikClient>} client
+ * @param {string} websiteId
+ * @param {string} [scope]
+ */
+/**
+ * Copy tracking ids from Piwik down into the local dimension map.
+ * @param {ReturnType<typeof resolvePiwikConfig>} config
+ */
+async function runPull(config) {
+  assertApiConfig(config)
+  console.log(
+    `[piwik] account=${config.account} website=${config.websiteId} env=${config.envName}${config.siteSource ? ` (${config.siteSource})` : ''}`,
+  )
+  console.log('[piwik] Pull copies tracking ids from Piwik down into the local map. Keys match on name.')
+  const locals = loadLocalDimensions(config)
+  console.log(`[piwik] local ${config.dimensionFiles.map((file) => file.replace(`${config.cwd}/`, '')).join(', ')}`)
+  const client = createPiwikClient({
+    account: config.account,
+    clientId: config.clientId,
+    clientSecret: config.clientSecret,
+  })
+  const remotes = await listSiteDimensions(client, config.websiteId, config.scope)
+  const plan = planLocalPull(locals, remotes)
+  console.log(
+    `[piwik] ${plan.inSync.length} in sync, ${plan.updates.length} to update in the repo, ${plan.missingInPiwik.length} missing in Piwik, ${plan.remoteOnly.length} only in Piwik`,
+  )
+  if (plan.updates.length > 0) {
+    console.log(
+      renderTable(
+        ['scope', 'key', 'in repo', 'tracking_id in Piwik'],
+        plan.updates.map((item) => [
+          item.local.scope,
+          item.local.key,
+          String(item.local.slot),
+          String(item.next),
+        ]),
+      ).join('\n'),
+    )
+  }
+  if (plan.updates.length === 0) {
+    console.log('[piwik] Nothing to write.')
+    return 0
+  }
+  if (config.dryRun) {
+    console.log('[piwik] Dry run. The local dimension map was not changed.')
+    return 0
+  }
+  const apply = await confirmApply(
+    `Write ${plan.updates.length} tracking id(s) from Piwik into the local dimension map?`,
+    config,
+  )
+  if (!apply) return 0
+
+  /** @type {Map<string, { key: string, from: number, to: number }[]>} */
+  const byFile = new Map()
+  for (const item of plan.updates) {
+    const list = byFile.get(item.local.file) ?? []
+    list.push({ key: item.local.key, from: item.local.slot, to: item.next })
+    byFile.set(item.local.file, list)
+  }
+  for (const [file, updates] of byFile) {
+    const absolute = file.startsWith('/') ? file : `${config.cwd}/${file}`
+    const source = fs.readFileSync(absolute, 'utf8')
+    fs.writeFileSync(absolute, rewriteDimensionNumbers(source, updates))
+    console.log(`[piwik] updated ${file.replace(`${config.cwd}/`, '')}`)
+  }
+  return 0
+}
+
+async function listSiteDimensions(client, websiteId, scope) {
+  const result = await client.listDimensions(websiteId)
+  const dimensions = scope ? result.dimensions.filter((item) => item.scope === scope) : result.dimensions
+  for (const remote of dimensions) {
+    if (!remote.websiteId) remote.websiteId = websiteId
+  }
+  return dimensions
+}
+
+/**
+ * @param {ReturnType<typeof resolvePiwikConfig>} config
+ */
+async function runEnvironmentCommand(config) {
+  const { from, to } = resolveEnvironmentPair(config.cwd, config.fromEnv, config.toEnv)
+  assertApiConfig({ ...config, account: from.account, websiteId: from.websiteId })
+  if (from.account !== to.account) {
+    throw new PiwikDimensionError(
+      `${from.environment} uses account ${from.account} and ${to.environment} uses ${to.account}. Compare and migrate need the same Piwik account.`,
+    )
+  }
+
+  console.log(`[piwik] from=${from.environment} website=${from.websiteId}`)
+  console.log(`[piwik] to=${to.environment} website=${to.websiteId}`)
+
+  const client = createPiwikClient({
+    account: from.account,
+    clientId: config.clientId,
+    clientSecret: config.clientSecret,
+  })
+  const source = await listSiteDimensions(client, from.websiteId, config.scope)
+  const target = await listSiteDimensions(client, to.websiteId, config.scope)
+  const diff = diffEnvironments(source, target)
+  const plan = planEnvironmentMigration(diff, target)
+  console.log(formatEnvironmentReport(diff, plan, from.environment, to.environment))
+
+  const drifted = diff.changed.length > 0 || diff.missing.length > 0 || diff.targetOnly.length > 0
+  if (config.command === 'compare') return drifted ? 1 : 0
+
+  if (diff.targetOnly.length > 0) {
+    console.log(`[piwik] ${diff.targetOnly.length} dimension(s) exist only in ${to.environment} and are left as they are.`)
+  }
+  if (plan.creates.length === 0 && diff.changed.length === 0) {
+    console.log('[piwik] Nothing to write.')
+    return plan.blocked.length > 0 ? 1 : 0
+  }
+  if (config.dryRun) {
+    console.log('[piwik] Dry run. No dimensions were created or updated.')
+    return plan.blocked.length > 0 ? 1 : 0
+  }
+
+  const apply = await confirmApply(
+    `Copy ${plan.creates.length} new and ${diff.changed.length} updated dimension(s) from ${from.environment} to ${to.environment}?`,
+    config,
+  )
+  if (!apply) return 0
+
+  /** @type {unknown} */
+  let writeError = null
+  try {
+    for (const { source: origin, target: current } of diff.changed) {
+      console.log(
+        `[piwik] updating ${current.scope} tracking_id ${current.trackingId} "${current.name}" -> "${origin.name}"`,
+      )
+      const updated =
+        current.scope === 'product'
+          ? await client.updateProductDimensionState(current, { name: origin.name, description: origin.description })
+          : await client.updateDimensionState(current, {
+              name: origin.name,
+              description: origin.description,
+              active: origin.active,
+            })
+      console.log(`[piwik] updated id ${updated.id} name "${updated.name}"`)
+    }
+
+    for (const local of plan.creates) {
+      const origin = source.find(
+        (item) =>
+          item.scope === local.scope && (item.scope === 'product' ? item.slot === local.slot : item.trackingId === local.slot),
+      )
+      if (!origin) {
+        throw new PiwikDimensionError(`Missing source dimension for ${local.scope} ${local.slot}.`)
+      }
+      console.log(`[piwik] creating ${origin.scope} ${origin.name} tracking_id ${origin.trackingId} on ${to.environment}`)
+      const created =
+        origin.scope === 'product'
+          ? await client.createProductDimension({
+              websiteId: to.websiteId,
+              name: origin.name,
+              slot: origin.slot,
+              description: origin.description,
+            })
+          : await client.createDimension({
+              websiteId: to.websiteId,
+              name: origin.name,
+              scope: origin.scope,
+              description: origin.description,
+              active: origin.active,
+            })
+      const assignedId = origin.scope === 'product' ? created.slot : created.trackingId
+      const expectedId = origin.scope === 'product' ? origin.slot : origin.trackingId
+      if (assignedId !== expectedId) {
+        throw new PiwikDimensionError(
+          `Piwik assigned ${created.scope} slot ${created.slot} (tracking_id ${created.trackingId}) to "${created.name}" on ${to.environment}, but ${from.environment} uses tracking_id ${expectedId}. Stopped before the next create.`,
+        )
+      }
+      console.log(`[piwik] created id ${created.id} ${created.scope} slot ${created.slot} tracking_id ${created.trackingId}`)
+    }
+  } catch (error) {
+    writeError = error
+  }
+
+  console.log('\n[piwik] Piwik after the update:')
+  const refreshedSource = await listSiteDimensions(client, from.websiteId, config.scope)
+  const refreshedTarget = await listSiteDimensions(client, to.websiteId, config.scope)
+  const nextDiff = diffEnvironments(refreshedSource, refreshedTarget)
+  const nextPlan = planEnvironmentMigration(nextDiff, refreshedTarget)
+  console.log(formatEnvironmentReport(nextDiff, nextPlan, from.environment, to.environment))
+  if (writeError) throw writeError
+
+  return nextPlan.creates.length > 0 || nextPlan.blocked.length > 0 || nextDiff.changed.length > 0 ? 1 : 0
+}
+
+main()
+  .then((code) => {
+    process.exitCode = code ?? 0
+  })
+  .catch((error) => {
+    const message = error instanceof Error ? error.message : String(error)
+    console.error(`[piwik] ${message}`)
+    if (!(error instanceof PiwikDimensionError) && error instanceof Error && error.stack) {
+      console.error(error.stack)
+    }
+    process.exitCode = 1
+  })