sizmo 0.4.0

package/lib/cli.mjs

@@ -0,0 +1,311 @@
+// lib/cli.mjs — global-flag parse → route → ctx → run → exit-code map. All commands run
+// in-process via registry (importable core). READ-ONLY router; never writes to GoHighLevel.
+import { fileURLToPath } from 'node:url';
+import { registry } from './registry.mjs';
+import { resolve, loadProfiles, saveProfiles, validateToken, mask, pitAgeDays } from './config.mjs';
+import { makeHttp } from './http.mjs';
+import { buildCtx } from './context.mjs';
+import { buildSchema } from './schema.mjs';
+import { GhlError, EXIT } from './errors.mjs';
+import { readFileSync } from 'node:fs';
+
+const VERSION = JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8')).version;
+
+export async function route(argv, io = {}) {
+  const write = io.write || ((s) => process.stdout.write(s));
+  const writeErr = io.writeErr || ((s) => process.stderr.write(s));
+  // pull global --profile + --json + --fresh/--no-cache
+  let profile = null, json = false, fresh = false; const rest = [];
+  for (let i = 0; i < argv.length; i++) {
+    if (argv[i] === '--profile' && argv[i + 1]) { profile = argv[++i]; continue; }
+    if (argv[i] === '--json') { json = true; rest.push(argv[i]); continue; }
+    if (argv[i] === '--fresh' || argv[i] === '--no-cache') { fresh = true; continue; }
+    rest.push(argv[i]);
+  }
+  const [cmd, ...args] = rest;
+
+  if (cmd === undefined || cmd === 'help' || cmd === '--help' || cmd === '-h') { write(helpText(VERSION)); return cmd ? EXIT.OK : EXIT.USAGE; }
+  if (cmd === 'version' || cmd === '--version' || cmd === '-V') { write(VERSION + '\n'); return EXIT.OK; }
+  if (cmd === 'schema') { write(JSON.stringify(await buildSchema(registry, EXIT), null, 2) + '\n'); return EXIT.OK; }
+
+  // router-level verbs: auth, config, api
+  if (cmd === 'auth' || cmd === 'config') return routerVerb(cmd, args, { profile, json, write, writeErr, readStdin: io.readStdin });
+  if (cmd === 'api') return apiVerb(args, { profile, json, write, writeErr });
+
+  // recipe commands: all run in-process via registry
+  const name = cmd === 'recipes' ? args.shift() : cmd;
+  try {
+    if (registry[name]) {
+      const creds = resolve(profile);
+      const tty = !!(io.tty ?? process.stdout.isTTY);
+      const ctx = buildCtx({ creds, globals: { json, tty, command: name, fresh } });
+      const mod = await registry[name]();
+      const parsed = parseArgs(args, mod.meta);          // validates against meta.flags; throws GhlError USAGE
+      const code = await mod.run(parsed, ctx);
+      ctx.out.flush();
+      return code ?? EXIT.OK;
+    }
+    throw new GhlError(`unknown command "${name ?? cmd}"`, EXIT.USAGE, 'sizmo help');
+  } catch (e) {
+    if (e instanceof GhlError) {
+      if (json) writeErr(JSON.stringify({ error: e.message, code: e.code, remediation: e.remediation }) + '\n');
+      else writeErr(e.message + (e.remediation ? `\n  fix: ${e.remediation}` : '') + '\n');
+      return e.code;
+    }
+    writeErr((e?.message || 'error') + '\n');
+    return EXIT.API;
+  }
+}
+export const run = route;
+
+export function parseArgs(args, meta) {
+  const out = { _: [] };
+  const flags = new Map((meta?.flags || []).map(f => [f.name, f]));
+  for (let i = 0; i < args.length; i++) {
+    const a = args[i];
+    if (a.startsWith('--')) {
+      const f = flags.get(a);
+      if (!f) { if (a === '--json') { out.json = true; continue; } throw new GhlError(`unknown flag ${a}`, EXIT.USAGE, `sizmo schema`); }
+      if (f.type === 'bool') out[a.slice(2)] = true;
+      else {
+        if (i + 1 >= args.length) throw new GhlError(`flag ${a} needs a value`, EXIT.USAGE, 'sizmo schema');
+        out[a.slice(2)] = f.type === 'int' ? Number(args[++i]) : args[++i];
+      }
+    } else out._.push(a);
+  }
+  return out;
+}
+function helpText(v) { return `sizmo ${v} — GoHighLevel read-only CLI (money always human-triggered)\n  sizmo <command> [--json] [--profile name] [--fresh]\n  commands: see  sizmo schema\n  sizmo auth status · sizmo config list|use|set|rm\n  --fresh / --no-cache  bypass 60s read cache (always re-fetches live data)\n  cacheAgeMs in JSON envelope shows how old the data is when served from cache\n`; }
+
+// routerVerb — auth + config local verbs.
+// io.readStdin seam lets tests inject stdin content without actually reading fd 0.
+async function routerVerb(cmd, args, io) {
+  const { profile = null, json = false, write, writeErr, readStdin } = io;
+  const [verb, ...rest] = args;
+
+  function die(msg, code = EXIT.API, remediation = null) {
+    if (json) writeErr(JSON.stringify({ error: msg, code, ...(remediation && { remediation }) }) + '\n');
+    else writeErr(msg + (remediation ? `\n  fix: ${remediation}` : '') + '\n');
+    return code;
+  }
+
+  // ── auth ────────────────────────────────────────────────────────────────────
+  if (cmd === 'auth') {
+    if (verb === 'check') {
+      // auth check: verify PIT scopes by probing the API directly
+      const creds = resolve(profile);
+      if (!creds.pit) return die('no credentials found', EXIT.AUTH, 'set GHL_PIT, or: sizmo config set --profile <name> --pit-stdin');
+      if (!creds.loc) return die('no location resolved', EXIT.AUTH, 'pass --profile <name>, or set GHL_LOCATION_ID');
+      write('auth check: probing GoHighLevel API scopes...\n');
+      try {
+        const http = makeHttp({ pit: creds.pit });
+        const result = await validateToken(http, creds.loc);
+        if (!result.ok) {
+          writeErr(`WARN: token check failed — ${result.reason}\n`);
+          return EXIT.AUTH;
+        }
+        write(`auth check: PIT accepted for location ${creds.loc}\n`);
+        return EXIT.OK;
+      } catch (e) {
+        writeErr(`auth check: could not reach GoHighLevel (${e?.message ?? 'error'})\n`);
+        return EXIT.API;
+      }
+    }
+    if (verb !== 'status') return die('usage: sizmo auth status|check', EXIT.USAGE);
+
+    // auth status — source, loc, masked PIT, age
+    const creds = resolve(profile);
+    write(`auth source   ${creds.source ?? 'NONE'}\n`);
+    write(`location      ${creds.loc ?? '(none resolved)'}\n`);
+    write(`PIT           ${mask(creds.pit)}${creds.label ? `  (${creds.label})` : ''}\n`);
+    const age = pitAgeDays(creds.createdAt);
+    if (age !== null) {
+      const note = age >= 90 ? '✖ EXPIRED-ZONE — rotate NOW (90d limit, 7d dual-token overlap)'
+        : age >= 80 ? `⚠ rotate soon — day ${age} of 90`
+        : `✅ day ${age} of 90`;
+      write(`PIT age       ${note}\n`);
+    } else {
+      write(`PIT age       unknown — set with: sizmo config set --profile <name> --created YYYY-MM-DD\n`);
+    }
+    if (!creds.pit) return die('no credentials found', EXIT.AUTH, 'set GHL_PIT, or: sizmo config set --profile <name> --pit-stdin');
+    return EXIT.OK;
+  }
+
+  // ── config ──────────────────────────────────────────────────────────────────
+  if (cmd === 'config') {
+    const db = loadProfiles();
+
+    if (verb === 'list') {
+      const names = Object.keys(db.profiles ?? {});
+      if (json) {
+        // Machine output — PIT never emitted (omitted entirely, not masked).
+        const profiles = names.map(n => {
+          const p = db.profiles[n];
+          return {
+            name: n,
+            locationId: p.locationId ?? null,
+            label: p.label ?? null,
+            default: n === db.default,
+            pitAgeDays: pitAgeDays(p.createdAt),
+          };
+        });
+        write(JSON.stringify({ schemaVersion: 1, profiles }) + '\n');
+        return EXIT.OK;
+      }
+      if (!names.length) {
+        write('no profiles yet (GHL_PIT env var in effect if set). sizmo config set --profile <name> ...\n');
+      }
+      for (const n of names) {
+        const p = db.profiles[n];
+        const age = pitAgeDays(p.createdAt);
+        write(`${n === db.default ? '*' : ' '} ${n.padEnd(16)} loc ${p.locationId ?? '—'}  ${mask(p.pit)}  ${age !== null ? `day ${age}/90` : ''}  ${p.label ?? ''}\n`);
+      }
+      return EXIT.OK;
+    }
+
+    if (verb === 'use') {
+      const name = rest[0];
+      if (!db.profiles?.[name]) return die(`no profile "${name}"`, EXIT.NOTFOUND, 'sizmo config list');
+      db.default = name;
+      saveProfiles(db);
+      write(`default → ${name}\n`);
+      return EXIT.OK;
+    }
+
+    if (verb === 'rm') {
+      const name = rest[0];
+      if (!db.profiles?.[name]) return die(`no profile "${name}"`, EXIT.NOTFOUND, 'sizmo config list');
+      delete db.profiles[name];
+      if (db.default === name) db.default = null;
+      saveProfiles(db);
+      write(`removed ${name}\n`);
+      return EXIT.OK;
+    }
+
+    if (verb === 'set') {
+      // flag(n): returns the value string when present, null when absent.
+      // Distinguish "flag absent" from "flag present with empty string" — reject empty strings.
+      const flagRaw = (n) => { const i = rest.indexOf(n); return i >= 0 ? (rest[i + 1] ?? null) : null; };
+      const flagPresent = (n) => rest.indexOf(n) >= 0;
+      const flag = (n) => { const v = flagRaw(n); return (v && v !== '') ? v : null; };
+      // Reject explicitly-passed empty strings for --loc, --label, --created
+      for (const f of ['--loc', '--label', '--created']) {
+        if (flagPresent(f) && !flagRaw(f)) return die(`${f} requires a non-empty value`, EXIT.USAGE, `sizmo config set --profile <name> ${f} <value>`);
+      }
+      const name = flag('--profile') ?? profile;
+      if (!name) return die('need --profile <name>', EXIT.USAGE);
+      db.profiles ??= {};
+      const p = db.profiles[name] ?? {};
+      if (flag('--loc')) p.locationId = flag('--loc');
+      if (flag('--label')) p.label = flag('--label');
+      if (flag('--created')) p.createdAt = flag('--created');
+
+      if (rest.includes('--pit-stdin')) {
+        let tok;
+        if (readStdin) {
+          tok = readStdin().trim();
+        } else {
+          tok = readFileSync(0, 'utf8').trim();
+        }
+        if (!tok.startsWith('pit-')) return die('stdin did not look like a PIT (expected pit-…)', EXIT.USAGE);
+        p.pit = tok;
+        p.createdAt ??= new Date().toISOString().slice(0, 10);
+      } else if (flag('--pit-env')) {
+        const envVar = flag('--pit-env');
+        const tok = process.env[envVar];
+        if (!tok?.startsWith('pit-')) return die(`env ${envVar} empty or not a PIT`, EXIT.USAGE);
+        p.pit = tok;
+        p.createdAt ??= new Date().toISOString().slice(0, 10);
+      }
+
+      db.profiles[name] = p;
+      db.default ??= name;
+      saveProfiles(db);
+      write(`saved ${name} — loc ${p.locationId ?? '—'} · ${mask(p.pit)} · ${p.createdAt ? 'created ' + p.createdAt : 'no created date'}\n`);
+
+      // validate PIT→loc after save (warn only — don't hard-fail the save)
+      if (p.pit && p.locationId) {
+        try {
+          const http = makeHttp({ pit: p.pit });
+          const result = await validateToken(http, p.locationId);
+          if (!result.ok) {
+            writeErr(`WARN: token validation failed — ${result.reason}\n  The profile was saved. Double-check PIT and loc before using.\n`);
+          }
+        } catch (e) {
+          writeErr(`WARN: could not reach GoHighLevel to validate token (${e?.message ?? 'error'}) — profile saved anyway\n`);
+        }
+      }
+
+      return EXIT.OK;
+    }
+
+    return die('usage: sizmo config list|use <name>|set --profile <name> ...|rm <name>', EXIT.USAGE);
+  }
+
+  return EXIT.OK;
+}
+
+// apiVerb — GET-only raw escape hatch.
+// Structural read-only: no method flag exists. Uses makeHttp instead of raw fetch.
+async function apiVerb(args, { profile, json, write, writeErr }) {
+  const [path, ...rest] = args;
+  function die(msg, code = EXIT.API, remediation = null) {
+    if (json) writeErr(JSON.stringify({ error: msg, code, ...(remediation && { remediation }) }) + '\n');
+    else writeErr(msg + (remediation ? `\n  fix: ${remediation}` : '') + '\n');
+    return code;
+  }
+
+  if (!path || !path.startsWith('/'))
+    return die('usage: sizmo api </path?query> [--paginate] [--max-pages N]', EXIT.USAGE, 'example: sizmo api "/contacts/?limit=5"');
+
+  const creds = resolve(profile);
+  if (!creds.pit)
+    return die('no PIT available', EXIT.AUTH, 'set GHL_PIT, or: sizmo config set --profile <name> --pit-stdin');
+
+  const flag = (n, d) => { const i = rest.indexOf(n); return i >= 0 && rest[i + 1] ? rest[i + 1] : d; };
+  const paginate = rest.includes('--paginate');
+  const rawMaxPages = flag('--max-pages', null);
+  const maxPages = rawMaxPages !== null ? Number(rawMaxPages) : 10;
+  // validate --max-pages when --paginate is set — NaN or <=0 produces empty output
+  if (paginate && rawMaxPages !== null && !(Number.isInteger(maxPages) && maxPages >= 1))
+    return die(`--max-pages must be a positive integer (got ${JSON.stringify(rawMaxPages)})`, EXIT.USAGE, 'example: sizmo api "/contacts/?limit=5" --paginate --max-pages 5');
+
+  const http = makeHttp({ pit: creds.pit });
+
+  // auto-fill locationId when absent
+  const LOC = creds.loc;
+  let urlPath = path;
+  if (LOC && !/locationId=|location_id=|altId=/.test(urlPath))
+    urlPath += (urlPath.includes('?') ? '&' : '?') + 'locationId=' + LOC;
+
+  const pages = [];
+  const BASE = 'https://services.leadconnectorhq.com';
+  let currentPath = urlPath;
+
+  for (let p = 0; p < (paginate ? maxPages : 1); p++) {
+    // For paginated next URLs, strip the base if present
+    const reqPath = currentPath.startsWith('http')
+      ? currentPath.replace(BASE, '')
+      : currentPath;
+    const r = await http.get(reqPath);
+    if (r.code === 401 || r.code === 403)
+      return die(`HTTP ${r.code} — PIT lacks scope for ${path}`, EXIT.AUTH, 'sizmo auth check shows which lanes this PIT can see');
+    if (r.code === 404)
+      return die(`HTTP 404 — ${path}`, EXIT.NOTFOUND, (r.txt || '').slice(0, 120).replace(/\s+/g, ' '));
+    if (!r.ok)
+      return die(`HTTP ${r.code} — ${(r.txt || '').slice(0, 200).replace(/\s+/g, ' ')}`, EXIT.API);
+
+    // If response isn't JSON (no j), write raw text and stop
+    if (r.j === null) { write(r.txt + '\n'); return EXIT.OK; }
+    pages.push(r.j);
+
+    const next = r.j?.meta?.nextPageUrl;
+    if (!paginate || !next) break;
+    currentPath = next;
+  }
+
+  write(JSON.stringify(pages.length === 1 ? pages[0] : pages, null, 2) + '\n');
+  if (paginate && pages.length === maxPages)
+    writeErr(`note: stopped at --max-pages ${maxPages}; more may exist\n`);
+  return EXIT.OK;
+}

package/lib/config.mjs

@@ -0,0 +1,39 @@
+// lib/config.mjs — credential resolution + profiles. NO baked location default.
+import { readFileSync, writeFileSync, mkdirSync, chmodSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { env as processEnv } from 'node:process';
+
+// XDG-style neutral config path. Override with XDG_CONFIG_HOME.
+const XDG = processEnv.XDG_CONFIG_HOME || join(homedir(), '.config');
+const CFG_DIR = join(XDG, 'sizmo');
+const PROFILES = join(CFG_DIR, 'profiles.json');
+
+export function loadProfiles() { try { return JSON.parse(readFileSync(PROFILES, 'utf8')); } catch { return { default: null, profiles: {} }; } }
+export function saveProfiles(db) { mkdirSync(CFG_DIR, { recursive: true }); writeFileSync(PROFILES, JSON.stringify(db, null, 2)); chmodSync(PROFILES, 0o600); }
+
+// pure + injectable for tests: precedence env > profile. NO default loc.
+export function resolveCreds(env, profile) {
+  const pit = env.GHL_PIT || profile?.pit || null;
+  const loc = env.GHL_LOCATION_ID || profile?.locationId || null;
+  const source = env.GHL_PIT ? 'env GHL_PIT' : profile?.pit ? 'profile' : null;
+  const tz = profile?.tz || 'UTC';
+  const currency = profile?.currency || null;
+  return { pit, loc, tz, currency, source };
+}
+export function resolve(profileName) {
+  const db = loadProfiles();
+  const name = profileName || db.default;
+  const profile = name ? db.profiles?.[name] : null;
+  const r = resolveCreds(process.env, profile);
+  return { ...r, profileName: name, profile, label: profile?.label, createdAt: profile?.createdAt };
+}
+// confirm the PIT actually belongs to loc (one live read). http = makeHttp(pit).
+export async function validateToken(http, loc) {
+  const r = await http.get('/contacts/', { query: { locationId: loc, limit: 1 } });
+  if (r.code === 401 || r.code === 403) return { ok: false, reason: `PIT rejected for ${loc} (HTTP ${r.code})` };
+  if (!r.ok && r.code !== 200) return { ok: false, reason: `unexpected HTTP ${r.code}` };
+  return { ok: true };
+}
+export const mask = (pit) => pit ? `pit-…${pit.slice(-4)}` : '(none)';
+export const pitAgeDays = (createdAt) => createdAt ? Math.floor((Date.now() - new Date(createdAt).getTime()) / 86400000) : null;

package/lib/context.mjs

@@ -0,0 +1,33 @@
+// lib/context.mjs — assemble the injected ctx. Enforces "no creds → AUTH".
+import { makeHttp } from './http.mjs';
+import { makeOut } from './output.mjs';
+import { makeCache } from './cache.mjs';
+import { GhlError, EXIT } from './errors.mjs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { env as processEnv } from 'node:process';
+
+// XDG-style neutral cache path. Override with XDG_CONFIG_HOME.
+const XDG = processEnv.XDG_CONFIG_HOME || join(homedir(), '.config');
+const CACHE_DIR = join(XDG, 'sizmo', 'cache');
+const CACHE_TTL_MS = 60_000; // 60 seconds
+
+export function buildCtx({ creds, globals, now = Date.now(), httpFactory = makeHttp } = {}) {
+  if (!creds.pit) throw new GhlError('no PIT available', EXIT.AUTH, 'set GHL_PIT, or: sizmo config set --profile <name> --pit-stdin');
+  if (!creds.loc) throw new GhlError('no location resolved', EXIT.AUTH, 'pass --profile <name>, or set GHL_LOCATION_ID');
+  // --fresh / --no-cache: bypass cache entirely (always re-fetch)
+  const fresh = !!(globals.fresh || globals['no-cache']);
+  // Cache is keyed by full URL (includes locationId param) — no cross-profile bleed
+  const cache = makeCache({ dir: CACHE_DIR, ttlMs: CACHE_TTL_MS });
+  const rawHttp = httpFactory({ pit: creds.pit, cache, fresh });
+  const out = makeOut({ json: !!globals.json, tty: !!globals.tty, command: globals.command, location: creds.loc });
+  // Wrap http.get to forward cacheAge to out.noteCacheAge — so flush() can surface it in the envelope/TTY note.
+  const http = {
+    get: async (path, opts) => {
+      const r = await rawHttp.get(path, opts);
+      if (typeof r.cacheAge === 'number') out.noteCacheAge(r.cacheAge);
+      return r;
+    },
+  };
+  return { http, cfg: creds, out, now };
+}

package/lib/errors.mjs

@@ -0,0 +1,11 @@
+// lib/errors.mjs — typed errors mapped to documented exit codes.
+export const EXIT = { OK: 0, API: 1, USAGE: 2, AUTH: 3, NOTFOUND: 4 };
+
+export class GhlError extends Error {
+  constructor(message, code = EXIT.API, remediation = null) {
+    super(message);
+    this.name = 'GhlError';
+    this.code = code;
+    this.remediation = remediation;
+  }
+}

package/lib/http.mjs

@@ -0,0 +1,52 @@
+// lib/http.mjs — the one GHL HTTP client. Auth, 429 Retry-After + backoff+jitter, timeout.
+// READ paths only are used by this CLI; method defaults to GET. fetch/sleep injectable for tests.
+const DEFAULT_BASE = 'https://services.leadconnectorhq.com';
+
+export function makeHttp({ pit, base = DEFAULT_BASE, version = '2021-07-28',
+                           fetch = globalThis.fetch, sleep = (ms) => new Promise(r => setTimeout(r, ms)),
+                           maxRetries = 4, timeoutMs = 15000, jitter = () => 0.5,
+                           maxTimeoutRetries = 2, cache = null, fresh = false } = {}) {
+  async function get(path, { query, version: v = version } = {}) {
+    const url = new URL(base + path);
+    if (query) for (const [k, val] of Object.entries(query)) if (val != null) url.searchParams.set(k, String(val));
+    // Cache check: full resolved URL as key (includes locationId param → no cross-profile bleed)
+    const cacheKey = url.toString();
+    if (cache && !fresh) {
+      const hit = cache.get(cacheKey);
+      if (hit) return { ...hit.value, cacheAge: hit.ageMs };
+    }
+    let attempt = 0;
+    let timeoutAttempt = 0;
+    while (true) {
+      const ctl = new AbortController();
+      const timer = setTimeout(() => ctl.abort(), timeoutMs);
+      let res;
+      try {
+        res = await fetch(url, { method: 'GET', signal: ctl.signal,
+          headers: { Authorization: `Bearer ${pit}`, Version: v, Accept: 'application/json' } });
+      } catch (e) {
+        clearTimeout(timer);
+        if (e.name === 'AbortError') {
+          if (timeoutAttempt++ < maxTimeoutRetries) { await sleep(backoff(timeoutAttempt, jitter)); continue; }
+          return { code: 0, ok: false, j: null, txt: 'timeout' };
+        }
+        if (attempt++ < maxRetries) { await sleep(backoff(attempt, jitter)); continue; }
+        return { code: 0, ok: false, j: null, txt: e.message };
+      }
+      clearTimeout(timer);
+      if (res.status === 429 && attempt < maxRetries) {
+        const ra = Number(res.headers.get?.('retry-after'));
+        await sleep(Number.isFinite(ra) && ra > 0 ? ra * 1000 : backoff(++attempt, jitter));
+        continue;
+      }
+      if (res.status >= 500 && attempt < maxRetries) { await sleep(backoff(++attempt, jitter)); continue; }
+      const txt = await res.text(); let j = null; try { j = JSON.parse(txt); } catch {}
+      const result = { code: res.status, ok: res.status >= 200 && res.status < 300, j, txt };
+      // Only cache 2xx responses — NEVER cache 4xx/5xx/blocked (fake-fresh bug class)
+      if (cache && !fresh && result.ok) cache.set(cacheKey, result);
+      return result;
+    }
+  }
+  return { get };
+}
+function backoff(attempt, jitter) { return Math.min(8000, 250 * 2 ** attempt) * (0.5 + jitter() * 0.5); }

package/lib/output.mjs

@@ -0,0 +1,39 @@
+// lib/output.mjs — bimodal output. TTY → human card; non-TTY/--json → frozen envelope. warn() always stderr.
+export function makeOut({ json, tty, command, location, write = (s) => process.stdout.write(s),
+                          writeErr = (s) => process.stderr.write(s) } = {}) {
+  const warnings = [];
+  let degraded = false;
+  let payload = null;
+  let flushed = false;
+  let maxCacheAgeMs = null; // null = no cache hits; number = max age (ms) across all cached responses
+  const api = {
+    color: tty && !process.env.NO_COLOR,
+    data(obj) { payload = obj; },                          // machine payload
+    warn(str, { degraded: d = false } = {}) { warnings.push(str); if (d) degraded = true; writeErr(str + '\n'); },
+    card(fn) { if (!json) fn(); },                          // human render (no-op in json mode)
+    line(s = '') { if (!json) write(s + '\n'); },
+    // Track the max cache age across all responses in this run.
+    // Called by context.mjs after each http.get() that returns a cacheAge.
+    noteCacheAge(ageMs) {
+      if (typeof ageMs === 'number') {
+        maxCacheAgeMs = maxCacheAgeMs === null ? ageMs : Math.max(maxCacheAgeMs, ageMs);
+      }
+    },
+    flush() {
+      if (flushed) return;
+      flushed = true;
+      // TTY cache note — never show cached data without surfacing the age
+      if (!json && maxCacheAgeMs !== null) {
+        const s = Math.round(maxCacheAgeMs / 1000);
+        write(`· cached ${s}s ago · --fresh to refresh\n`);
+      }
+      if (json) {
+        const envelope = { schemaVersion: 1, command, location, data: payload, degraded, warnings };
+        if (maxCacheAgeMs !== null) envelope.cacheAgeMs = maxCacheAgeMs;
+        write(JSON.stringify(envelope, null, 2) + '\n');
+      }
+    },
+    get degraded() { return degraded; },
+  };
+  return api;
+}

package/lib/paginate.mjs

@@ -0,0 +1,13 @@
+// lib/paginate.mjs — strategy-driven, fetch-to-completion. The structural fix for shallow single-page reads.
+export async function* paginate({ fetchPage, getItems, nextCursor, maxPages = 100, startCursor } = {}) {
+  let cursor = startCursor, pages = 0;
+  while (pages < maxPages) {
+    const resp = await fetchPage(cursor);
+    pages++;
+    const items = getItems(resp) || [];
+    for (const it of items) yield it;
+    const next = nextCursor(resp, items, cursor);
+    if (next == null) return;
+    cursor = next;
+  }
+}

package/lib/pool.mjs

@@ -0,0 +1,10 @@
+// lib/pool.mjs — concurrency-capped parallel map. Order-preserving. For rate-limit-safe fan-out.
+export async function mapLimit(items, limit, fn) {
+  const out = new Array(items.length);
+  let i = 0;
+  async function worker() {
+    while (i < items.length) { const idx = i++; out[idx] = await fn(items[idx], idx); }
+  }
+  await Promise.all(Array.from({ length: Math.min(limit, items.length) }, worker));
+  return out;
+}

package/lib/prioritize.mjs

@@ -0,0 +1,146 @@
+// lib/prioritize.mjs — Transparent money-at-stake ranker.
+// Pure function, no I/O. Honesty law: rank ONLY by money we can actually see.
+// Items with no known value go to a SEPARATE unknownValue group — never faked as ₱0.
+// Every output line shows its inputs. No hidden score. No currency conversion.
+
+const SYM = { PHP: '₱', USD: '$', EUR: '€', GBP: '£' };
+const fmt = (n, c = 'PHP') => (SYM[c] || c + ' ') + Number(n || 0).toLocaleString('en-PH', { maximumFractionDigits: 0 });
+
+/**
+ * rankActions({ deals, invoices, threads, noshows, neverBilled })
+ *
+ * Each input array element shape:
+ *   deals:       { contactId, name, monetaryValue, ageDays }
+ *   invoices:    { contactId, name, due, cur, ageDays }
+ *   threads:     { contactId, name, ageDays }                — no known money
+ *   noshows:     { contactId, name, ageDays }                — no known money
+ *   neverBilled: { contactId, name, estValue, ageDays }      — estValue>0 counts; 0/null → unknownValue
+ *
+ * Returns:
+ *   ranked      — money items, sorted money desc, tie-break age desc
+ *                 each: { money, cur, age, kind, contact, name, action, inputs }
+ *   unknownValue — threads + noshows + zero-est neverBilled, sorted age desc
+ *                 each: { money:null, age, kind, contact, name, action, inputs }
+ *
+ * Mixed-currency caveat: sort is by raw number with currency labeled per line.
+ * PHP 1000 vs USD 100 — the sort compares raw values without conversion.
+ * If mixed currencies are present in ranked, callers should surface a caveat footer.
+ */
+export function rankActions({
+  deals = [],
+  invoices = [],
+  threads = [],
+  noshows = [],
+  neverBilled = [],
+} = {}) {
+  const ranked = [];
+  const unknownValue = [];
+
+  // ── deals: monetaryValue>0 → ranked; 0/unset → unknownValue ──────────────────
+  // A deal with no monetaryValue is value-UNKNOWN (coach didn't enter one), NOT worth ₱0.
+  // Faking it as ₱0 and ranking it at the bottom of the money list is the fake-intelligence
+  // bug — an unset value is unknown, surfaced honestly, never a fabricated zero.
+  for (const d of deals) {
+    const money = Number(d.monetaryValue) || 0;
+    // GHL opportunity monetaryValue has no currency field — treated as PHP (known GHL limitation)
+    if (money > 0) {
+      ranked.push({
+        money, cur: 'PHP', age: d.ageDays, kind: 'deal', contact: d.contactId, name: d.name,
+        action: 'ghl pipeline', inputs: `${fmt(money, 'PHP')} deal · idle ${d.ageDays}d`,
+      });
+    } else {
+      unknownValue.push({
+        money: null, age: d.ageDays, kind: 'deal', contact: d.contactId, name: d.name,
+        action: 'ghl pipeline', inputs: `open deal · no value set · idle ${d.ageDays}d · value unknown`,
+      });
+    }
+  }
+
+  // ── invoices: due>0 → ranked; ≤0 → unknownValue (defensive; receivables only returns due>0) ──
+  for (const i of invoices) {
+    const money = Number(i.due) || 0;
+    const cur = (i.cur || 'PHP').toUpperCase();
+    if (money > 0) {
+      ranked.push({
+        money, cur, age: i.ageDays, kind: 'invoice', contact: i.contactId, name: i.name,
+        action: 'ghl receivables', inputs: `${fmt(money, cur)} invoice due · aged ${i.ageDays}d`,
+      });
+    } else {
+      unknownValue.push({
+        money: null, age: i.ageDays, kind: 'invoice', contact: i.contactId, name: i.name,
+        action: 'ghl receivables', inputs: `invoice · no balance shown · aged ${i.ageDays}d · value unknown`,
+      });
+    }
+  }
+
+  // ── never-billed: real estValue>0 → ranked; 0/null/undefined → unknownValue ──
+  for (const b of neverBilled) {
+    const est = Number(b.estValue);
+    if (est > 0) {
+      ranked.push({
+        money: est,
+        cur: 'PHP',
+        age: b.ageDays,
+        kind: 'never-billed',
+        contact: b.contactId,
+        name: b.name,
+        action: 'ghl booked-not-paid',
+        inputs: `${fmt(est, 'PHP')} est. value · never billed · last session ${b.ageDays}d ago`,
+      });
+    } else {
+      unknownValue.push({
+        money: null,
+        age: b.ageDays,
+        kind: 'never-billed',
+        contact: b.contactId,
+        name: b.name,
+        action: 'ghl booked-not-paid',
+        inputs: `never billed · last session ${b.ageDays}d ago · value unknown`,
+      });
+    }
+  }
+
+  // ── threads (waiting on reply) — no known money ───────────────────────────
+  for (const t of threads) {
+    unknownValue.push({
+      money: null,
+      age: t.ageDays,
+      kind: 'waiting-reply',
+      contact: t.contactId,
+      name: t.name,
+      action: 'ghl triage',
+      inputs: `waiting ${t.ageDays}d · value unknown`,
+    });
+  }
+
+  // ── noshows — no known money ───────────────────────────────────────────────
+  for (const n of noshows) {
+    unknownValue.push({
+      money: null,
+      age: n.ageDays,
+      kind: 'noshow',
+      contact: n.contactId,
+      name: n.name,
+      action: 'ghl noshow',
+      inputs: `no-show ${n.ageDays}d ago · value unknown`,
+    });
+  }
+
+  // ── sort ───────────────────────────────────────────────────────────────────
+  // ranked: money desc, tie-break age desc (older = more urgent)
+  ranked.sort((a, b) => b.money - a.money || b.age - a.age);
+  // unknownValue: age desc
+  unknownValue.sort((a, b) => b.age - a.age);
+
+  return { ranked, unknownValue };
+}
+
+/**
+ * hasMixedCurrencies(ranked) → boolean
+ * True when ranked items span more than one currency.
+ * Callers use this to surface the "raw-number sort, currencies labeled" caveat.
+ */
+export function hasMixedCurrencies(ranked) {
+  const currencies = new Set(ranked.map(x => x.cur));
+  return currencies.size > 1;
+}