shakers-cli 0.0.0-stage → 0.14.0

package/src/email-verification.js

@@ -0,0 +1,152 @@
+'use strict';
+
+const { requestBackend } = require('./backend-request');
+
+// Email-verification client + wait-mode loop (skill-code-certification, ADR-006).
+
+const DEFAULT_TIMEOUT_MS = 15000;
+// Bounded so a Talent who can never produce a matching code can't loop forever — after this many CODE-ENTRY attempts we give up (nothing persisted, asked again next run).
+const MAX_CODE_ATTEMPTS = 5;
+
+// POST {email} to the request endpoint.
+async function requestCode({ email }, { url, timeoutMs = DEFAULT_TIMEOUT_MS } = {}) {
+  if (!url) return { ok: false, reason: 'no-endpoint' };
+
+  let res;
+  try {
+    res = await requestBackend({ endpoint: url, body: { email }, timeoutMs });
+  } catch (e) {
+    if (e && e.kind === 'timeout') return { ok: false, reason: 'timeout' };
+    return { ok: false, reason: 'network-error', detail: e && e.message };
+  }
+
+  if (res.status < 200 || res.status >= 300) {
+    return { ok: false, reason: `http-${res.status}` };
+  }
+  return { ok: true, backend: res.backend };
+}
+
+// Maps a server "not verified" outcome to a soft reason the loop can retry on.
+function mapNotVerifiedReason(bodyReason) {
+  return bodyReason === 'expired' ? 'expired' : 'invalid-code';
+}
+
+// POST {email, code} to the verify endpoint.
+async function verifyCode({ email, code }, { url, timeoutMs = DEFAULT_TIMEOUT_MS } = {}) {
+  if (!url) return { ok: false, reason: 'no-endpoint' };
+
+  let res;
+  try {
+    res = await requestBackend({ endpoint: url, body: { email, code }, timeoutMs });
+  } catch (e) {
+    if (e && e.kind === 'timeout') return { ok: false, reason: 'timeout' };
+    return { ok: false, reason: 'network-error', detail: e && e.message };
+  }
+
+  let parsed = null;
+  try {
+    parsed = res.raw ? JSON.parse(res.raw) : null;
+  } catch {
+    // fall through: unparseable body handled per status below
+  }
+
+  if (res.status >= 200 && res.status < 300) {
+    if (parsed && parsed.verified === true) return { ok: true, verified: true, backend: res.backend };
+    if (parsed && typeof parsed === 'object') return { ok: false, reason: mapNotVerifiedReason(parsed.reason) };
+    return { ok: false, reason: 'invalid-json' };
+  }
+
+  // Non-2xx: a bad/expired code the server rejects at the HTTP layer is still
+  // a SOFT failure (retryable). 5xx and anything else is technical.
+  if (res.status === 400 || res.status === 401 || res.status === 410 || res.status === 422) {
+    return { ok: false, reason: mapNotVerifiedReason(parsed && parsed.reason) };
+  }
+  return { ok: false, reason: `http-${res.status}` };
+}
+
+// Categorizes a verifyCode reason for the wait-mode loop: 'soft' -> invalid/expired code: show a message, keep waiting (retry).
+function classifyVerifyReason(reason) {
+  if (reason === 'invalid-code' || reason === 'expired') return 'soft';
+  return 'technical';
+}
+
+// The interactive "modo espera": send a code, then loop reading the pasted code until it verifies, the Talent cancels, or attempts run out.
+// talents-ai-score, ADR-042: `requestUrl`/`verifyUrl` address the ONE backend (the certifications service).
+async function runEmailVerification({
+  email,
+  ask,
+  catalog,
+  requestUrl,
+  verifyUrl,
+  deps = {},
+}) {
+  const v = catalog.verify;
+  const doRequest = deps.requestCode || requestCode;
+  const doVerify = deps.verifyCode || verifyCode;
+  const write = deps.write || ((s) => process.stdout.write(s));
+
+  // No endpoint could be derived (ingest unset): nothing to verify against,
+  // and nowhere to persist either. Quiet, non-error outcome.
+  if (!requestUrl || !verifyUrl) {
+    write(`  ${v.unavailable}\n`);
+    return { verified: false, reason: 'unavailable' };
+  }
+
+  const sent = await doRequest({ email }, { url: requestUrl });
+  if (!sent.ok) {
+    write(`  ${v.requestFailed}\n`);
+    return { verified: false, reason: 'request-failed' };
+  }
+
+  // Entered wait mode.
+  write(`\n  ${v.sent(email)}\n`);
+  write(`  ${v.waitHint}\n`);
+
+  for (let attempt = 0; attempt < MAX_CODE_ATTEMPTS; ) {
+    // The OTP is a secret too (issue 102): same reader, same echo, and the fix is the same call.
+    const readCode = typeof ask.secret === 'function' ? ask.secret.bind(ask) : ask;
+    const raw = String(await readCode(v.codePrompt)).trim();
+
+    // Empty line / EOF (piped, closed stdin) / Ctrl-C-then-Enter -> cancel.
+    if (raw === '') {
+      write(`  ${v.cancelled}\n`);
+      return { verified: false, reason: 'cancelled' };
+    }
+
+    // Resend, without consuming an attempt.
+    if (/^r$/i.test(raw)) {
+      const resent = await doRequest({ email }, { url: requestUrl });
+      write(resent.ok ? `  ${v.resent(email)}\n` : `  ${v.resendFailed}\n`);
+      continue;
+    }
+
+    attempt++;
+    const result = await doVerify({ email, code: raw }, { url: verifyUrl });
+    if (result.ok && result.verified) {
+      write(`  ${v.verified}\n`);
+      return { verified: true, backend: result.backend };
+    }
+
+    if (classifyVerifyReason(result.reason) === 'soft') {
+      write(result.reason === 'expired' ? `  ${v.expired}\n` : `  ${v.invalidCode}\n`);
+      continue;
+    }
+
+    // Technical: the Hub couldn't be reached or answered unexpectedly. Legible
+    // error, bail out (nothing persisted); the report was already shown.
+    write(`  ${v.technicalError}\n`);
+    return { verified: false, reason: 'technical' };
+  }
+
+  write(`  ${v.tooManyAttempts}\n`);
+  return { verified: false, reason: 'exhausted' };
+}
+
+module.exports = {
+  requestCode,
+  verifyCode,
+  classifyVerifyReason,
+  runEmailVerification,
+  DEFAULT_TIMEOUT_MS,
+  MAX_CODE_ATTEMPTS,
+};

package/src/env-paths.js

@@ -0,0 +1,30 @@
+'use strict';
+
+const os = require('os');
+
+// Shared home-directory + env resolution (talents-ai-score, ADR-014 — "Alcance del tier: Talento = proyecto ∪ home", applied uniformly to every category).
+function readEnv(env, suffix) {
+  const next = env[`SHAKERS_CLI_${suffix}`];
+  if (next !== undefined && next !== '') return next;
+  return env[`AI_FOOTPRINT_${suffix}`];
+}
+
+function getHomeDir(env = process.env) {
+  return readEnv(env, 'HOME_DIR') || os.homedir();
+}
+
+// `~/Documents/cv.pdf` -> absolute, so a model can pass the short form it was shown.
+function expandHome(file, env = process.env) {
+  if (typeof file !== 'string') return file;
+  if (file === '~') return getHomeDir(env);
+  if (file.startsWith('~/')) return require('path').join(getHomeDir(env), file.slice(2));
+  return file;
+}
+
+// The short `~/...` form of a path under home, for showing (and copying) without typos.
+function tildify(file, env = process.env) {
+  const home = getHomeDir(env);
+  return typeof file === 'string' && file.startsWith(`${home}/`) ? `~/${file.slice(home.length + 1)}` : file;
+}
+
+module.exports = { getHomeDir, readEnv, expandHome, tildify };

package/src/find-projects-cache.js

@@ -0,0 +1,89 @@
+'use strict';
+
+// Ordinal -> positionId cache for the LAST human `find-projects` listing, so the
+// terminal user can reference a project by the `N)` number they saw (the
+// positionId is hidden from the human render). Written only on a human list,
+// never on --json. Atomic 0600, same dir/style as the session store.
+
+const crypto = require('crypto');
+const fs = require('fs');
+const path = require('path');
+const { getConfigDir } = require('./config-dir');
+
+const CACHE_FILE_NAME = 'find-projects-cache.json';
+const CACHE_FILE_VERSION = 1;
+
+function cachePath(env = process.env) {
+  // Containment guard: the file name is a constant with no separators, so this
+  // can never escape — but resolving + checking closes the path-traversal gate
+  // cheaply and makes the invariant explicit. Throws on any escape; callers that
+  // read swallow it (return null), callers that write propagate (best-effort).
+  const base = path.resolve(getConfigDir(env));
+  const target = path.resolve(base, CACHE_FILE_NAME);
+  const rel = path.relative(base, target);
+  if (rel === '' || rel.startsWith('..') || path.isAbsolute(rel)) {
+    throw new Error('find-projects cache path escapes the config dir');
+  }
+  return target;
+}
+
+// Persists the display-ordered positionIds (index i -> ordinal i+1).
+function writePositionCache(ids, env = process.env, { fs: fsImpl = fs } = {}) {
+  const clean = (Array.isArray(ids) ? ids : []).filter((id) => typeof id === 'string' && id);
+  const payload = `${JSON.stringify({ version: CACHE_FILE_VERSION, listedAt: new Date().toISOString(), ids: clean }, null, 2)}\n`;
+  const target = cachePath(env);
+  const dir = path.dirname(target);
+  fsImpl.mkdirSync(dir, { recursive: true, mode: 0o700 });
+  const tmp = path.join(dir, `.${CACHE_FILE_NAME}.${process.pid}.${crypto.randomBytes(6).toString('hex')}.tmp`);
+  let fd = null;
+  try {
+    fd = fsImpl.openSync(tmp, 'wx', 0o600);
+    fsImpl.writeFileSync(fd, payload);
+    try { fsImpl.fsyncSync(fd); } catch { /* e.g. EINVAL on some filesystems */ }
+    fsImpl.closeSync(fd);
+    fd = null;
+    fsImpl.renameSync(tmp, target);
+  } catch (e) {
+    if (fd !== null) { try { fsImpl.closeSync(fd); } catch { /* already closed */ } }
+    try { fsImpl.unlinkSync(tmp); } catch { /* never existed */ }
+    throw e;
+  }
+  return target;
+}
+
+// Returns the stored id list, or null when there is no usable cache.
+function readPositionCache(env = process.env, { fs: fsImpl = fs } = {}) {
+  let parsed;
+  try {
+    parsed = JSON.parse(fsImpl.readFileSync(cachePath(env), 'utf8'));
+  } catch {
+    return null;
+  }
+  if (!parsed || typeof parsed !== 'object' || parsed.version !== CACHE_FILE_VERSION || !Array.isArray(parsed.ids)) return null;
+  const ids = parsed.ids.filter((id) => typeof id === 'string' && id);
+  return { ids };
+}
+
+// Resolves a raw positional argument to a positionId. A PURE integer is an
+// ordinal into the last listing's cache; anything else (UUID / legacy Mongo id)
+// is passed through unchanged. Never resolves to the wrong project silently.
+function resolvePositionRef(raw, env = process.env, deps = {}) {
+  const read = deps.readPositionCache || readPositionCache;
+  const arg = typeof raw === 'string' ? raw.trim() : '';
+  if (!arg) return { ok: false, reason: 'no-id' };
+  if (!/^\d+$/.test(arg)) return { ok: true, id: arg }; // UUID / Mongo id passthrough
+  const n = Number.parseInt(arg, 10);
+  const cache = read(env);
+  if (!cache || cache.ids.length === 0) return { ok: false, reason: 'no-cache' };
+  if (n < 1 || n > cache.ids.length) return { ok: false, reason: 'out-of-range', count: cache.ids.length };
+  return { ok: true, id: cache.ids[n - 1] };
+}
+
+module.exports = {
+  CACHE_FILE_NAME,
+  CACHE_FILE_VERSION,
+  cachePath,
+  writePositionCache,
+  readPositionCache,
+  resolvePositionRef,
+};

package/src/find-projects-client.js

@@ -0,0 +1,148 @@
+'use strict';
+
+// Find Positions list client. Each
+// item carries the parent Project's id/name — a "project" here is the Position's
+// parent, not a separate list. Pagination (limit/offset) and filters map to the
+// endpoint's `criteria`; the server orders by match desc and returns the total.
+
+const { postJsonWithTimeout } = require('./backend-request');
+const { reasonForError } = require('./onboarding-client');
+
+const DEFAULT_TIMEOUT_MS = 20000;
+const DEFAULT_LIMIT = 15;
+// Only tabs the endpoint distinguishes server-side: All (default order) and
+// Saved (savedByMe). "Recommended" was a client illusion — dropped under
+// pagination, where it would only cover the fetched page and mislead.
+const TABS = ['all', 'saved'];
+const ATTENDANCE = { remote: 'REMOTE', hybrid: 'HYBRID', 'in-person': 'IN_PERSON' };
+
+function parseJson(raw) {
+  try {
+    return raw ? JSON.parse(raw) : null;
+  } catch {
+    return null;
+  }
+}
+
+function bearerHeaders(accessToken) {
+  const headers = {};
+  if (typeof accessToken === 'string' && accessToken) headers.Authorization = `Bearer ${accessToken}`;
+  return headers;
+}
+
+function pick(obj, keys) {
+  for (const k of keys) {
+    const v = obj && obj[k];
+    if (v !== undefined && v !== null && v !== '') return v;
+  }
+  return null;
+}
+
+function numOrNull(v) {
+  return typeof v === 'number' && Number.isFinite(v) ? v : null;
+}
+
+function strArray(v) {
+  return Array.isArray(v) ? v.filter((x) => typeof x === 'string' && x) : [];
+}
+
+// Only fields the readview's criteria map supports server-side: savedByMe,
+// attendance, country, clusterIds (confirmed in FindPositionsService + its prisma readview).
+// languages and skills are output-only (no filter field) → not built here.
+function buildCriteria(tab, { limit = DEFAULT_LIMIT, offset = 0, attendance = null, country = null, clusterId = null } = {}) {
+  const criteria = { limit, offset };
+  const conditions = [];
+  if (tab === 'saved') conditions.push({ field: 'savedByMe', operator: 'EQUALS', value: true });
+  if (clusterId) conditions.push({ field: 'clusterIds', operator: 'IN', value: [clusterId] });
+  if (attendance) conditions.push({ field: 'attendance', operator: 'IN', value: [attendance] });
+  if (country) conditions.push({ field: 'country', operator: 'IN', value: [country] });
+  if (conditions.length) criteria.filter = { conjunction: 'AND', conditions };
+  return criteria;
+}
+
+function normalizeItem(raw) {
+  const it = raw && typeof raw === 'object' ? raw : {};
+  const company = it.company && typeof it.company === 'object' ? it.company : {};
+  const budget = it.budget && typeof it.budget === 'object' ? it.budget : null;
+  return {
+    positionId: pick(it, ['positionId', 'id']),
+    title: pick(it, ['title']),
+    projectId: pick(it, ['projectId']),
+    projectName: pick(it, ['projectName']),
+    description: pick(it, ['description']),
+    country: pick(it, ['country']),
+    requiredMonthlyHours: numOrNull(it.requiredMonthlyHours),
+    attendance: pick(it, ['attendance']),
+    match: numOrNull(it.match),
+    isSaved: it.isSaved === true,
+    company: {
+      name: pick(company, ['name']),
+      restricted: company.restricted === true,
+    },
+    budget: budget
+      ? {
+        from: numOrNull(budget.from),
+        to: numOrNull(budget.to),
+        unit: pick(budget, ['unit']),
+        display: pick(budget, ['display']),
+      }
+      : null,
+    skillNames: strArray(it.skillNames),
+    languages: strArray(it.languages),
+  };
+}
+
+async function requestFindProjects(
+  { hubAccessToken } = {},
+  { tab = 'all', endpoint, timeoutMs = DEFAULT_TIMEOUT_MS, limit = DEFAULT_LIMIT, offset = 0, attendance = null, country = null, clusterId = null } = {},
+) {
+  if (!endpoint) return { ok: false, reason: 'no-endpoint' };
+  if (!hubAccessToken) return { ok: false, reason: 'no-hub-token' };
+
+  const criteria = buildCriteria(tab, { limit, offset, attendance, country, clusterId });
+  const url = `${endpoint}${endpoint.includes('?') ? '&' : '?'}criteria=${encodeURIComponent(JSON.stringify(criteria))}`;
+  let res;
+  try {
+    res = await postJsonWithTimeout(url, null, timeoutMs, 'GET', null, bearerHeaders(hubAccessToken));
+  } catch (e) {
+    return { ok: false, reason: (e && e.kind) || 'network-error' };
+  }
+  if (res.status < 200 || res.status >= 300) return { ok: false, reason: reasonForError(res.status, res.raw) };
+
+  const env = parseJson(res.raw);
+  if (!env || typeof env !== 'object') return { ok: false, reason: 'bad-response' };
+  const data = env.status === 'OK' ? env.data : env;
+  const rows = Array.isArray(data) ? data : (Array.isArray(data && data.items) ? data.items : null);
+  if (!rows) return { ok: false, reason: 'bad-response' };
+  return { ok: true, items: rows.map(normalizeItem), meta: (env && typeof env.meta === 'object' ? env.meta : null) };
+}
+
+// CLI+MCP entry: resolve the endpoint from config, then fetch one page.
+async function fetchFindProjects(deps = {}, { hubAccessToken, tab = 'all', timeoutMs = DEFAULT_TIMEOUT_MS, limit = DEFAULT_LIMIT, offset = 0, attendance = null, country = null, clusterId = null } = {}) {
+  const {
+    getFindPositionsEndpoint = require('./config').getFindPositionsEndpoint,
+    requestFindProjects: request = requestFindProjects,
+  } = deps;
+  const endpoint = getFindPositionsEndpoint();
+  if (!endpoint) return { ok: false, reason: 'no-endpoint' };
+  return request({ hubAccessToken }, { tab, endpoint, timeoutMs, limit, offset, attendance, country, clusterId });
+}
+
+// Open positions visible to the talent that look for one role (cluster): the list's own total, one row fetched.
+async function countOpenPositions(deps = {}, { hubAccessToken, clusterId, timeoutMs = DEFAULT_TIMEOUT_MS } = {}) {
+  const res = await fetchFindProjects(deps, { hubAccessToken, timeoutMs, limit: 1, clusterId });
+  if (!res.ok) return res;
+  const total = res.meta && Number.isInteger(res.meta.total) ? res.meta.total : null;
+  return total === null ? { ok: false, reason: 'no-total' } : { ok: true, total };
+}
+
+module.exports = {
+  TABS,
+  countOpenPositions,
+  ATTENDANCE,
+  DEFAULT_LIMIT,
+  buildCriteria,
+  normalizeItem,
+  requestFindProjects,
+  fetchFindProjects,
+};

package/src/find-projects-flow.js

@@ -0,0 +1,164 @@
+'use strict';
+
+// `find-projects` flow: list the Positions/Projects available to the talent,
+// paginated and filtered server-side via the endpoint's `criteria`. Read-only.
+
+const { TABS, ATTENDANCE, DEFAULT_LIMIT } = require('./find-projects-client');
+const { styleLabelPrefix } = require('./ansi');
+
+function makeFindProjectsDeps(overrides = {}) {
+  const client = require('./find-projects-client');
+  return {
+    fetchFindProjects: (opts) => client.fetchFindProjects({}, opts),
+    writePositionCache: (ids) => require('./find-projects-cache').writePositionCache(ids),
+    ...overrides,
+  };
+}
+
+// Normalize CLI/agent inputs to the shapes the endpoint's criteria expects.
+function resolveQuery(opts = {}) {
+  const tab = TABS.includes(opts.tab) ? opts.tab : 'all';
+  const limit = Number.isInteger(opts.limit) && opts.limit > 0 ? Math.min(opts.limit, 50) : DEFAULT_LIMIT;
+  const page = Number.isInteger(opts.page) && opts.page > 0 ? opts.page : 1;
+  const offset = (page - 1) * limit;
+  const attRaw = typeof opts.attendance === 'string' ? opts.attendance.trim().toLowerCase() : null;
+  const attendance = attRaw && ATTENDANCE[attRaw] ? ATTENDANCE[attRaw] : null;
+  const attendanceInvalid = !!(attRaw && !ATTENDANCE[attRaw]);
+  const countryRaw = typeof opts.country === 'string' ? opts.country.trim().toUpperCase() : null;
+  const country = countryRaw && /^[A-Z]{2}$/.test(countryRaw) ? countryRaw : null;
+  const countryInvalid = !!(countryRaw && !/^[A-Z]{2}$/.test(countryRaw));
+  return { tab, limit, page, offset, attendance, country, attendanceInvalid, countryInvalid, recommended: !!opts.recommended };
+}
+
+// `--recommended` is a CLIENT-SIDE filter over the fetched page (the hub has no
+// server-side "recommended" criterion — `match` is output-only). Recommended =
+// items that have a match. If none on this page, fall back to the available
+// items so the user is never left with an empty screen.
+function splitRecommended(items, recommended) {
+  if (!recommended) return { shown: items, mode: null };
+  const rec = items.filter((it) => it.match != null);
+  if (rec.length > 0) return { shown: rec, mode: 'recommended' };
+  return { shown: items, mode: 'fallback' };
+}
+
+function budgetLine(item, fp) {
+  if (item.budget && item.budget.display) return item.budget.display;
+  if (item.budget && (item.budget.from != null || item.budget.to != null)) {
+    return `${item.budget.from ?? '·'}–${item.budget.to ?? '·'}${item.budget.unit ? ` ${item.budget.unit}` : ''}`;
+  }
+  return fp.budgetUnknown;
+}
+
+function formatItem(item, index, fp) {
+  const headline = item.title || item.projectName || fp.untitled;
+  const company = item.company && item.company.name
+    ? item.company.name
+    : (item.company && item.company.restricted ? fp.companyRestricted : null);
+  // No type segment (positions-only, always "position" → redundant).
+  const metaBits = [
+    item.attendance || null,
+    item.country || null,
+    item.requiredMonthlyHours != null ? fp.hoursPerMonth(item.requiredMonthlyHours) : null,
+    budgetLine(item, fp),
+    item.match != null ? fp.matchScore(item.match) : null,
+    item.isSaved ? fp.savedBadge : null,
+  ].filter(Boolean);
+  // Human render never prints positionId/projectId (they stay in --json only).
+  const lines = [`${index}) ${headline}${company ? ` — ${company}` : ''}`];
+  if (item.projectName && item.projectName !== headline) lines.push(`   ${styleLabelPrefix(fp.projectLabel(item.projectName))}`);
+  lines.push(`   ${metaBits.join(' · ')}`);
+  return lines.join('\n  ');
+}
+
+// "Showing X–Y of TOTAL" (+ a next-page hint while more pages remain).
+function paginationFooter(fp, meta, q, shown) {
+  if (!meta || typeof meta.total !== 'number') return null;
+  if (meta.total === 0) return null;
+  const from = q.offset + 1;
+  const to = q.offset + shown;
+  let line = fp.showing(from, to, meta.total);
+  if (meta.totalPages && q.page < meta.totalPages) line += ` · ${fp.morePages(q.page + 1)}`;
+  return line;
+}
+
+// Honest footer while showing the client-side recommended SUBSET of a page:
+// never "X of TOTAL" (TOTAL is all available, not recommended). Pagination still
+// works to pull more pages (which may carry more recommended).
+function recommendedFooter(fp, count, meta, q) {
+  let line = fp.recommendedOnPage(count);
+  if (meta && meta.totalPages && q.page < meta.totalPages) line += ` · ${fp.morePages(q.page + 1)}`;
+  return line;
+}
+
+async function runFindProjects({ io, rawOut, session, lang, catalog, opts = {}, deps = makeFindProjectsDeps() }) {
+  const fp = catalog.findProjects;
+  const hubAccessToken = session ? session.hubAccessToken : null;
+  const q = resolveQuery(opts);
+
+  if (!opts.json) {
+    if (q.attendanceInvalid) io.warn(fp.attendanceIgnored);
+    if (q.countryInvalid) io.warn(fp.countryIgnored);
+  }
+
+  // In --json the loading label must not print (it would corrupt the JSON on a
+  // non-TTY stdout); only decorate the human path with the progress spinner.
+  const fetchPage = () => deps.fetchFindProjects({
+    hubAccessToken, tab: q.tab, limit: q.limit, offset: q.offset, attendance: q.attendance, country: q.country,
+  });
+  const res = opts.json ? await fetchPage() : await io.withProgress(fp.loading, fetchPage);
+  if (!res.ok) {
+    io.error(fp.fetchFailed(res.reason));
+    return { ok: false, reason: res.reason };
+  }
+
+  const items = Array.isArray(res.items) ? res.items : [];
+  // Client-side recommended filter (+ fallback to available), applied to both
+  // the human render and --json so an agent sees the same view (json keeps match).
+  const { shown, mode } = splitRecommended(items, q.recommended);
+
+  if (opts.json) {
+    (rawOut || ((s) => process.stdout.write(s)))(`${JSON.stringify({
+      ok: true,
+      tab: q.tab,
+      page: q.page,
+      limit: q.limit,
+      filters: { attendance: q.attendance, country: q.country, recommended: q.recommended },
+      recommended: mode,
+      meta: res.meta || null,
+      items: shown,
+    }, null, 2)}\n`);
+    return { ok: true, items: shown, meta: res.meta || null, recommended: mode };
+  }
+
+  // Persist the ordinal -> positionId map of what is SHOWN so `show-project N`
+  // matches the render. Human path only; a write failure never breaks the listing.
+  try { deps.writePositionCache(shown.map((it) => it.positionId)); } catch { /* cache is best-effort */ }
+
+  io.section(q.tab === 'saved' ? fp.titleSaved : fp.title);
+  if (items.length === 0) {
+    io.notify(q.page > 1 ? fp.noneOnPage : fp.noneAvailable);
+    return { ok: true, items: shown, meta: res.meta || null, recommended: mode };
+  }
+  // No recommended on this page -> we show the available ones, with a clear notice.
+  if (mode === 'fallback') io.notify(fp.recommendedNoneFallback);
+  shown.forEach((item, i) => {
+    if (i > 0) io.notify('');
+    io.notify(formatItem(item, i + 1, fp));
+  });
+  const footer = mode === 'recommended'
+    ? recommendedFooter(fp, shown.length, res.meta, q)
+    : paginationFooter(fp, res.meta, q, shown.length);
+  if (footer) io.notify(footer);
+  io.success(fp.done);
+  return { ok: true, items: shown, meta: res.meta || null, recommended: mode };
+}
+
+module.exports = {
+  makeFindProjectsDeps,
+  runFindProjects,
+  resolveQuery,
+  splitRecommended,
+  formatItem,
+  paginationFooter,
+  recommendedFooter,
+};