shakers-cli-beta 0.8.0-beta.0

package/src/roadmap-personalization.js

@@ -0,0 +1,132 @@
+'use strict';
+
+const { requestBackend } = require('./backend-request');
+const { reporterFor, REASON } = require('./model-call-record');
+
+// Roadmap personalization client (talents-ai-score, ADR-015).
+
+const DEFAULT_TIMEOUT_MS = 8000;
+
+/* ---------- signals (derived only, never raw content) ---------- */
+
+// Builds the `signals` block from data this report ALREADY computes elsewhere (nothing new is read from disk here).
+function buildRoadmapSignals(report, tierSignals) {
+  const r = report || {};
+  const ts = tierSignals || {};
+  return {
+    frameworks: Array.isArray(r.technologies) ? r.technologies : [],
+    toolCategories: r.summary && Array.isArray(r.summary.categories) ? r.summary.categories : [],
+    mcpCategories: (r.mcp && r.mcp.countsByCategory) || { data: 0, comms: 0, dev: 0, browser: 0, other: 0 },
+    // Agent NAMES only — never descriptions/prompts (same whitelist
+    // src/agent-org-chart.js's parseAgentOrgChart already enforces).
+    agents: Array.isArray(r.agents) ? r.agents.map((a) => a.name) : [],
+    agentCounts: r.agentCounts || { agents: 0, skills: 0, commands: 0, mcpServers: 0, hooks: 0 },
+    hooks: typeof ts.hooks === 'number' ? ts.hooks : 0,
+    automations: r.automations || null,
+  };
+}
+
+// Builds the exact wire request: `{tier, tierKey, curated, signals}`.
+function buildRoadmapPersonalizationRequest(curatedEntry, tierResult, report, locale = null, consentGranted = false) {
+  return {
+    tier: tierResult.tier,
+    tierKey: tierResult.tierKey,
+    curated: {
+      whatUnlocks: curatedEntry.unlocks,
+      steps: curatedEntry.steps,
+      tips: curatedEntry.tips,
+      mistakes: curatedEntry.commonMistakes,
+    },
+    signals: buildRoadmapSignals(report, tierResult.signals),
+    // ADR-026: detected report language for the personalized prose.
+    ...(locale === 'es' || locale === 'en' ? { locale } : {}),
+    ...(consentGranted === true ? { traceContentConsent: true } : {}),
+  };
+}
+
+/* ---------- validation: all-or-nothing against the curated counts ---------- */
+
+function isValidPersonalizedRoadmap(parsed, curated) {
+  if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) return false;
+  if (typeof parsed.whatUnlocks !== 'string' || !parsed.whatUnlocks.trim()) return false;
+
+  if (!Array.isArray(parsed.steps) || parsed.steps.length !== curated.steps.length) return false;
+  if (!parsed.steps.every((s) => s && typeof s.text === 'string' && s.text.trim())) return false;
+
+  if (!Array.isArray(parsed.tips) || parsed.tips.length !== curated.tips.length) return false;
+  if (!parsed.tips.every((tip) => typeof tip === 'string' && tip.trim())) return false;
+
+  if (!Array.isArray(parsed.mistakes) || parsed.mistakes.length !== curated.mistakes.length) return false;
+  if (!parsed.mistakes.every((m) => typeof m === 'string' && m.trim())) return false;
+
+  return true;
+}
+
+/* ---------- network (via the shared PRIMARY -> FALLBACK chain) ---------- */
+
+// Requests the roadmap personalization endpoint.
+async function requestRoadmapPersonalization(requestBody, { endpoint, timeoutMs = DEFAULT_TIMEOUT_MS, onOutcome = null } = {}) {
+  // Issue 109 — see agent-synthesis.js#requestAgentSynthesis for the contract.
+  const outcome = reporterFor(onOutcome, { timeoutMs });
+  if (!endpoint) {
+    outcome.skip(REASON.NO_ENDPOINT);
+    return null;
+  }
+
+  let res;
+  try {
+    res = await requestBackend({ endpoint, body: requestBody, timeoutMs, trace: outcome.hops });
+  } catch (e) {
+    outcome.failFromError(e);
+    return null; // network error or timeout on every hop: never breaks the local report
+  }
+
+  if (res.status < 200 || res.status >= 300) {
+    outcome.fail(REASON.HTTP, { status: res.status, backend: res.backend });
+    return null;
+  }
+
+  let parsed;
+  try {
+    parsed = JSON.parse(res.raw);
+  } catch {
+    outcome.fail(REASON.MALFORMED_JSON, { status: res.status, backend: res.backend });
+    return null; // malformed (non-JSON) response body
+  }
+
+  if (!isValidPersonalizedRoadmap(parsed, requestBody.curated)) {
+    outcome.fail(REASON.UNEXPECTED_SHAPE, { status: res.status, backend: res.backend });
+    return null;
+  }
+
+  outcome.succeed({ status: res.status, backend: res.backend });
+  return {
+    whatUnlocks: parsed.whatUnlocks,
+    steps: parsed.steps,
+    tips: parsed.tips,
+    mistakes: parsed.mistakes,
+  };
+}
+
+/* ---------- merge: only the 4 prose gaps ever change ---------- */
+
+function mergeRoadmapPersonalization(curatedEntry, personalized) {
+  if (curatedEntry.maxTier || !personalized) return curatedEntry;
+  const curatedForValidation = { steps: curatedEntry.steps, tips: curatedEntry.tips, mistakes: curatedEntry.commonMistakes };
+  if (!isValidPersonalizedRoadmap(personalized, curatedForValidation)) return curatedEntry;
+  return {
+    ...curatedEntry,
+    unlocks: personalized.whatUnlocks,
+    steps: personalized.steps,
+    tips: personalized.tips,
+    commonMistakes: personalized.mistakes,
+  };
+}
+
+module.exports = {
+  buildRoadmapSignals,
+  buildRoadmapPersonalizationRequest,
+  isValidPersonalizedRoadmap,
+  requestRoadmapPersonalization,
+  mergeRoadmapPersonalization,
+};

package/src/roadmap-prompt.js

@@ -0,0 +1,154 @@
+'use strict';
+
+const { tierName: getTierName } = require('./i18n');
+
+// Deterministic, ready-to-paste "implementation prompt" (talents-ai-score: "next steps -> prompt").
+
+const TEMPLATES = {
+  es: {
+    intro: (frameworksText) =>
+      `Ayúdame a implementar el siguiente paso en mi proyecto${frameworksText ? ` (uso ${frameworksText})` : ''}.`,
+    context: (tierKey, tierName) =>
+      `Contexto: mi proyecto está en el tier ${tierKey} (${tierName}) según AI Footprint, una herramienta de auto-diagnóstico de uso de IA.`,
+    unlocksLabel: 'Lo que quiero conseguir:',
+    toolsLabel: 'Herramientas de IA que ya uso:',
+    stepsLabel: 'Pasos a seguir:',
+    snippetLabel: 'Punto de partida (referencia — adáptalo a mi proyecto real):',
+    closing:
+      'Hazlo directamente en mi proyecto: crea o edita lo que haga falta, sigue las convenciones que ya uso, '
+      + 'y al final explícame brevemente qué has cambiado y por qué.',
+    introMax: (frameworksText) =>
+      `Ayúdame a consolidar y afinar el setup de IA de mi proyecto${frameworksText ? ` (uso ${frameworksText})` : ''}.`,
+    contextMax: (tierKey, tierName) =>
+      `Contexto: mi proyecto ya está en el tier máximo ${tierKey} (${tierName}) según AI Footprint. No busco añadir más herramientas, sino sacarle más partido a lo que ya tengo.`,
+    remainsLabel: 'Dónde está el margen ahora:',
+    stepsLabelMax: 'Refinamientos a aplicar:',
+    closingMax:
+      'Revisa mi proyecto y aplícalo directamente: recorta lo que estorbe, afina lo existente y '
+      + 'sigue las convenciones que ya uso; al final explícame brevemente qué has cambiado y por qué.',
+  },
+  en: {
+    intro: (frameworksText) =>
+      `Help me implement the next step in my project${frameworksText ? ` (I use ${frameworksText})` : ''}.`,
+    context: (tierKey, tierName) =>
+      `Context: my project is at tier ${tierKey} (${tierName}) according to AI Footprint, a self-diagnostic tool for AI usage.`,
+    unlocksLabel: 'What I want to achieve:',
+    toolsLabel: 'AI tools I already use:',
+    stepsLabel: 'Steps to follow:',
+    snippetLabel: 'Starting point (reference — adapt it to my actual project):',
+    closing:
+      "Do it directly in my project: create or edit whatever's needed, follow the conventions I already use, "
+      + 'and briefly explain at the end what you changed and why.',
+    introMax: (frameworksText) =>
+      `Help me consolidate and sharpen my project's AI setup${frameworksText ? ` (I use ${frameworksText})` : ''}.`,
+    contextMax: (tierKey, tierName) =>
+      `Context: my project is already at the top tier ${tierKey} (${tierName}) according to AI Footprint. I'm not looking to add more tools, but to get more out of what I already have.`,
+    remainsLabel: 'Where the margin is now:',
+    stepsLabelMax: 'Refinements to apply:',
+    closingMax:
+      'Review my project and apply it directly: trim what gets in the way, sharpen what exists and '
+      + 'follow the conventions I already use; briefly explain at the end what you changed and why.',
+  },
+};
+
+function resolveTemplate(lang) {
+  return TEMPLATES[lang] || TEMPLATES.es;
+}
+
+// `entry` is the roadmap entry ALREADY resolved by the caller (curated, or curated-with-personalization-merged — src/roadmap-personalization.js's mergeRoadmapPersonalization).
+function buildImplementationPrompt(entry, report, maturity, lang) {
+  if (!entry) return null;
+  if (entry.maxTier) return buildConsolidationPrompt(entry, report, maturity, lang);
+
+  const T = resolveTemplate(lang);
+  const r = report || {};
+  const frameworks = Array.isArray(r.technologies) ? r.technologies : [];
+  const toolNames = Array.isArray(r.tools) ? r.tools.filter((x) => x && x.detected).map((x) => x.name) : [];
+  const tierKey = (maturity && maturity.tierKey) || entry.tierKey || '';
+  // talents-ai-score, i18n audit: NEVER maturity.tierName directly — that field comes straight from tier-engine.js and is Spanish-only by design (domain logic, not i18n).
+  const tierName = getTierName(tierKey, lang);
+
+  const lines = [];
+  lines.push(T.intro(frameworks.join(', ')));
+  lines.push('');
+  lines.push(T.context(tierKey, tierName));
+  lines.push('');
+  lines.push(T.unlocksLabel);
+  lines.push(entry.unlocks);
+
+  if (toolNames.length) {
+    lines.push('');
+    lines.push(T.toolsLabel);
+    lines.push(toolNames.join(', '));
+  }
+
+  lines.push('');
+  lines.push(T.stepsLabel);
+  const steps = Array.isArray(entry.steps) ? entry.steps : [];
+  steps.forEach((s, i) => {
+    lines.push(`${i + 1}. ${s.text}${s.estimate ? ` (${s.estimate})` : ''}`);
+  });
+
+  if (entry.snippet && entry.snippet.code) {
+    lines.push('');
+    lines.push(T.snippetLabel);
+    if (entry.snippet.filename) lines.push(`${entry.snippet.filename}:`);
+    lines.push('```' + (entry.snippet.language || ''));
+    lines.push(entry.snippet.code);
+    lines.push('```');
+    if (entry.snippet.secondFile) {
+      lines.push('');
+      lines.push(`${entry.snippet.secondFile.filename}:`);
+      lines.push('```' + (entry.snippet.language || ''));
+      lines.push(entry.snippet.secondFile.code);
+      lines.push('```');
+    }
+  }
+
+  lines.push('');
+  lines.push(T.closing);
+
+  return lines.join('\n');
+}
+
+function buildConsolidationPrompt(entry, report, maturity, lang) {
+  const steps = Array.isArray(entry.consolidationSteps) ? entry.consolidationSteps : [];
+  if (steps.length === 0 && !entry.whatRemains) return null;
+
+  const T = resolveTemplate(lang);
+  const r = report || {};
+  const frameworks = Array.isArray(r.technologies) ? r.technologies : [];
+  const toolNames = Array.isArray(r.tools) ? r.tools.filter((x) => x && x.detected).map((x) => x.name) : [];
+  const tierKey = (maturity && maturity.tierKey) || entry.tierKey || 'T7';
+  const tierName = getTierName(tierKey, lang);
+
+  const lines = [];
+  lines.push(T.introMax(frameworks.join(', ')));
+  lines.push('');
+  lines.push(T.contextMax(tierKey, tierName));
+
+  if (entry.whatRemains) {
+    lines.push('');
+    lines.push(T.remainsLabel);
+    lines.push(entry.whatRemains);
+  }
+
+  if (toolNames.length) {
+    lines.push('');
+    lines.push(T.toolsLabel);
+    lines.push(toolNames.join(', '));
+  }
+
+  if (steps.length) {
+    lines.push('');
+    lines.push(T.stepsLabelMax);
+    steps.forEach((s, i) => lines.push(`${i + 1}. ${s}`));
+  }
+
+  lines.push('');
+  lines.push(T.closingMax);
+
+  return lines.join('\n');
+}
+
+module.exports = { buildImplementationPrompt };

package/src/roles-client.js

@@ -0,0 +1,114 @@
+'use strict';
+
+// Role/cluster hub clients (talent Bearer): list the addable catalog, list the
+// talent's own assigned roles, add a GROWTH role, and set the MAIN role.
+
+const { postJsonWithTimeout } = require('./backend-request');
+const { reasonForError } = require('./onboarding-client');
+
+const DEFAULT_TIMEOUT_MS = 20000;
+
+function parseJson(raw) {
+  try {
+    return raw ? JSON.parse(raw) : null;
+  } catch {
+    return null;
+  }
+}
+
+function envelopeData(raw) {
+  const json = parseJson(raw);
+  if (!json || typeof json !== 'object') return undefined;
+  return json.status === 'OK' ? json.data : json;
+}
+
+function bearerHeaders(hubAccessToken) {
+  const headers = {};
+  if (typeof hubAccessToken === 'string' && hubAccessToken) headers.Authorization = `Bearer ${hubAccessToken}`;
+  return headers;
+}
+
+function normalizeRole(r) {
+  if (!r || typeof r !== 'object') return null;
+  const clusterId = typeof r.clusterId === 'string' ? r.clusterId : null;
+  if (!clusterId) return null;
+  return {
+    clusterId,
+    name: typeof r.name === 'string' ? r.name : null,
+    category: typeof r.category === 'string' ? r.category : null,
+    proposalKind: typeof r.proposalKind === 'string' ? r.proposalKind : null,
+    type: typeof r.type === 'string' ? r.type : null,
+  };
+}
+
+// GET works/certifications/me/available-roles -> { roles:[{clusterId,name,category,proposalKind}] }.
+async function requestAvailableRoles({ hubAccessToken } = {}, { endpoint, timeoutMs = DEFAULT_TIMEOUT_MS } = {}) {
+  if (!endpoint) return { ok: false, reason: 'no-endpoint' };
+  if (!hubAccessToken) return { ok: false, reason: 'no-hub-token' };
+  let res;
+  try {
+    res = await postJsonWithTimeout(endpoint, 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 data = envelopeData(res.raw);
+  const rows = data && Array.isArray(data.roles) ? data.roles : (Array.isArray(data) ? data : null);
+  if (!rows) return { ok: false, reason: 'bad-response' };
+  return { ok: true, roles: rows.map(normalizeRole).filter(Boolean) };
+}
+
+// GET works/talents/me/work-details/assigned-clusters -> the talent's GROWTH/RECOMMENDED roles.
+async function requestAssignedClusters({ hubAccessToken } = {}, { endpoint, timeoutMs = DEFAULT_TIMEOUT_MS } = {}) {
+  if (!endpoint) return { ok: false, reason: 'no-endpoint' };
+  if (!hubAccessToken) return { ok: false, reason: 'no-hub-token' };
+  let res;
+  try {
+    res = await postJsonWithTimeout(endpoint, 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 data = envelopeData(res.raw);
+  const rows = Array.isArray(data) ? data : (data && Array.isArray(data.clusters) ? data.clusters : null);
+  if (!rows) return { ok: false, reason: 'bad-response' };
+  return { ok: true, clusters: rows.map(normalizeRole).filter(Boolean) };
+}
+
+// POST works/talents/me/work-details/assigned-clusters { clusterId } -> adds a GROWTH role.
+async function requestAddGrowthRole({ clusterId, hubAccessToken } = {}, { endpoint, timeoutMs = DEFAULT_TIMEOUT_MS } = {}) {
+  if (!endpoint) return { ok: false, reason: 'no-endpoint' };
+  if (!hubAccessToken) return { ok: false, reason: 'no-hub-token' };
+  if (typeof clusterId !== 'string' || !clusterId) return { ok: false, reason: 'no-cluster' };
+  let res;
+  try {
+    res = await postJsonWithTimeout(endpoint, { clusterId }, timeoutMs, 'POST', 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) };
+  return { ok: true, clusterId };
+}
+
+// PATCH works/certifications/me/main-role { clusterId } -> sets the preferred main role.
+async function requestSetMainRole({ clusterId, hubAccessToken } = {}, { endpoint, timeoutMs = DEFAULT_TIMEOUT_MS } = {}) {
+  if (!endpoint) return { ok: false, reason: 'no-endpoint' };
+  if (!hubAccessToken) return { ok: false, reason: 'no-hub-token' };
+  if (typeof clusterId !== 'string' || !clusterId) return { ok: false, reason: 'no-cluster' };
+  let res;
+  try {
+    res = await postJsonWithTimeout(endpoint, { clusterId }, timeoutMs, 'PATCH', 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) };
+  return { ok: true, clusterId };
+}
+
+module.exports = {
+  normalizeRole,
+  requestAvailableRoles,
+  requestAssignedClusters,
+  requestAddGrowthRole,
+  requestSetMainRole,
+};

package/src/roles-flow.js

@@ -0,0 +1,192 @@
+'use strict';
+
+// Shared role flows: add a GROWTH role, change the MAIN role, and the onboarding
+// final main-role step. Every choice uses the dynamic arrow selector (io.select).
+
+function makeRolesDeps(overrides = {}) {
+  const config = require('./config');
+  const client = require('./roles-client');
+  const certs = require('./certifications-client');
+  return {
+    getAvailableRolesEndpoint: config.getAvailableRolesEndpoint,
+    getSetMainRoleEndpoint: config.getSetMainRoleEndpoint,
+    getAssignedClustersEndpoint: config.getAssignedClustersEndpoint,
+    getMyCertificationsEndpoint: config.getMyCertificationsEndpoint,
+    requestAvailableRoles: client.requestAvailableRoles,
+    requestAssignedClusters: client.requestAssignedClusters,
+    requestAddGrowthRole: client.requestAddGrowthRole,
+    requestSetMainRole: client.requestSetMainRole,
+    requestMeCertifications: (args, opts) => certs.requestMeCertifications(args, opts),
+    ...overrides,
+  };
+}
+
+function roleLabel(role) {
+  if (!role) return '';
+  const name = role.name || role.clusterId;
+  return role.category ? `${name} — ${role.category}` : name;
+}
+
+function dedupeByCluster(roles) {
+  const seen = new Set();
+  const out = [];
+  for (const r of roles || []) {
+    if (!r || !r.clusterId || seen.has(r.clusterId)) continue;
+    seen.add(r.clusterId);
+    out.push(r);
+  }
+  return out;
+}
+
+async function chooseRole({ io, roles, header, hint, initialClusterId = null }) {
+  const initialMarked = [];
+  if (initialClusterId) {
+    const idx = roles.findIndex((r) => r.clusterId === initialClusterId);
+    if (idx >= 0) initialMarked.push(idx);
+  }
+  return io.select({ header, hint, items: roles, labelFor: roleLabel, initialMarked });
+}
+
+// `add-role`: list the addable catalog and add the chosen one as a GROWTH role.
+async function runAddRole({ io, session, catalog, deps = makeRolesDeps() }) {
+  const r = catalog.roles;
+  const hubAccessToken = session ? session.hubAccessToken : null;
+
+  const listEndpoint = deps.getAvailableRolesEndpoint();
+  const res = await io.withProgress(r.loadingAvailable, () =>
+    deps.requestAvailableRoles({ hubAccessToken }, { endpoint: listEndpoint }));
+  if (!res.ok) {
+    io.error(r.fetchFailed(res.reason));
+    return { ok: false, reason: res.reason };
+  }
+  const roles = dedupeByCluster(res.roles);
+  if (roles.length === 0) {
+    io.notify(r.noneAvailable);
+    return { ok: true, added: null };
+  }
+
+  io.section(r.addTitle);
+  const choice = await chooseRole({ io, roles, header: r.addPrompt, hint: r.selectHint });
+  if (!choice) {
+    io.notify(r.cancelled);
+    return { ok: true, added: null };
+  }
+
+  const addEndpoint = deps.getAssignedClustersEndpoint();
+  const added = await io.withProgress(r.savingAdd, () =>
+    deps.requestAddGrowthRole({ clusterId: choice.clusterId, hubAccessToken }, { endpoint: addEndpoint }));
+  if (!added.ok) {
+    if (added.reason === 'already-assigned') { io.warn(r.alreadyAssigned(roleLabel(choice))); return { ok: true, added: choice.clusterId }; }
+    io.error(r.addFailed(added.reason));
+    return { ok: false, reason: added.reason };
+  }
+  io.success(r.addedOk(roleLabel(choice)));
+  return { ok: true, added: choice.clusterId };
+}
+
+// Candidate roles the talent already holds (their own GROWTH picks + growing-into),
+// deduped, for setting/switching the MAIN role.
+async function fetchHeldRoles({ deps, hubAccessToken }) {
+  const held = [];
+  let mainClusterId = null;
+  const certEndpoint = deps.getMyCertificationsEndpoint();
+  if (certEndpoint) {
+    const cert = await deps.requestMeCertifications({ hubAccessToken }, { endpoint: certEndpoint });
+    if (cert.ok) {
+      if (cert.mainRole && cert.mainRole.clusterId) { held.push(cert.mainRole); mainClusterId = cert.mainRole.clusterId; }
+      for (const g of cert.growingInto || []) held.push(g);
+    }
+  }
+  const assignedEndpoint = deps.getAssignedClustersEndpoint();
+  if (assignedEndpoint) {
+    const assigned = await deps.requestAssignedClusters({ hubAccessToken }, { endpoint: assignedEndpoint });
+    if (assigned.ok) for (const c of assigned.clusters || []) held.push(c);
+  }
+  return { held: dedupeByCluster(held), mainClusterId };
+}
+
+// `change-role`: switch the MAIN role to one of the roles the talent already holds.
+async function runChangeMainRole({ io, session, catalog, deps = makeRolesDeps() }) {
+  const r = catalog.roles;
+  const hubAccessToken = session ? session.hubAccessToken : null;
+
+  const { held, mainClusterId } = await io.withProgress(r.loadingHeld, () => fetchHeldRoles({ deps, hubAccessToken }));
+  const candidates = held.filter((c) => c.clusterId !== mainClusterId);
+  if (candidates.length === 0) {
+    io.notify(r.noOtherRoles);
+    return { ok: true, changed: null };
+  }
+
+  io.section(r.changeTitle);
+  const current = held.find((c) => c.clusterId === mainClusterId);
+  if (current) io.notify(r.currentMain(roleLabel(current)));
+  const choice = await chooseRole({ io, roles: candidates, header: r.changePrompt, hint: r.selectHint });
+  if (!choice) {
+    io.notify(r.cancelled);
+    return { ok: true, changed: null };
+  }
+  return applySetMain({ io, deps, hubAccessToken, choice, catalog });
+}
+
+// The onboarding final step: pick a MAIN role from the roles resolved for the
+// talent (interview recommendations + any held). Degrades gracefully to a skip.
+async function runOnboardingMainRoleStep({ io, session, catalog, deps = makeRolesDeps() }) {
+  const r = catalog.roles;
+  const hubAccessToken = session ? session.hubAccessToken : null;
+
+  io.section(r.mainRoleTitle);
+  const { held, mainClusterId } = await io.withProgress(r.loadingHeld, () => fetchHeldRoles({ deps, hubAccessToken }));
+
+  // Prefer the talent's own/recommended roles; fall back to the catalog for a
+  // fresh talent so a main role can always be set (picking one adds it first).
+  let roles = held;
+  let fromCatalog = false;
+  if (held.length === 0) {
+    const av = await deps.requestAvailableRoles({ hubAccessToken }, { endpoint: deps.getAvailableRolesEndpoint() });
+    roles = av.ok ? dedupeByCluster(av.roles) : [];
+    fromCatalog = true;
+  }
+  if (roles.length === 0) {
+    io.notify(r.mainRolePending);
+    return { ok: true, chosen: null };
+  }
+  const choice = await chooseRole({
+    io, roles, header: r.mainRolePrompt, hint: r.selectHint, initialClusterId: mainClusterId,
+  });
+  if (!choice) {
+    io.notify(r.mainRoleSkipped);
+    return { ok: true, chosen: null };
+  }
+  if (choice.clusterId === mainClusterId) {
+    io.notify(r.mainRoleUnchanged(roleLabel(choice)));
+    return { ok: true, chosen: choice.clusterId };
+  }
+  // main-role requires the cluster to be a held assignment: add it first if it came from the catalog.
+  if (fromCatalog) {
+    await deps.requestAddGrowthRole({ clusterId: choice.clusterId, hubAccessToken }, { endpoint: deps.getAssignedClustersEndpoint() });
+  }
+  return applySetMain({ io, deps, hubAccessToken, choice, catalog });
+}
+
+async function applySetMain({ io, deps, hubAccessToken, choice, catalog }) {
+  const r = catalog.roles;
+  const endpoint = deps.getSetMainRoleEndpoint();
+  const set = await io.withProgress(r.savingMain, () =>
+    deps.requestSetMainRole({ clusterId: choice.clusterId, hubAccessToken }, { endpoint }));
+  if (!set.ok) {
+    io.error(r.setMainFailed(set.reason));
+    return { ok: false, reason: set.reason };
+  }
+  io.success(r.mainSetOk(roleLabel(choice)));
+  return { ok: true, chosen: choice.clusterId, changed: choice.clusterId };
+}
+
+module.exports = {
+  makeRolesDeps,
+  roleLabel,
+  dedupeByCluster,
+  fetchHeldRoles,
+  runAddRole,
+  runChangeMainRole,
+  runOnboardingMainRoleStep,
+};

package/src/sanitize-network-text.js

@@ -0,0 +1,36 @@
+'use strict';
+
+// Making text that came off the wire SAFE TO DISPLAY.
+
+// eslint-disable-next-line no-control-regex
+const CONTROL_CHARS_RE = /[\x00-\x08\x0B-\x1F\x7F]/g;
+
+const INVISIBLE_CHARS_RE =
+  /[\u00AD\u061C\u115F\u1160\u17B4\u17B5\u180E\u200B-\u200F\u2028\u2029\u202A-\u202E\u2060-\u2064\u2066-\u2069\u3164\uFEFF\uFFA0]|[\u{E0000}-\u{E007F}]/gu;
+
+function stripControlChars(s) {
+  if (typeof s !== 'string') return '';
+  return s.replace(CONTROL_CHARS_RE, '');
+}
+
+// Replaces every bidi/invisible character with a visible `[U+XXXX]` token.
+function markInvisibleChars(s) {
+  if (typeof s !== 'string') return '';
+  return s.replace(INVISIBLE_CHARS_RE, (ch) => {
+    const hex = ch.codePointAt(0).toString(16).toUpperCase();
+    return `[U+${hex.length < 4 ? hex.padStart(4, '0') : hex}]`;
+  });
+}
+
+// What every renderer should call on text that came off the wire before painting it.
+function sanitizeRenderText(s) {
+  return markInvisibleChars(stripControlChars(s));
+}
+
+// `jsonEscapeInvisibleChars` WAS HERE, and what is missing is the SURFACE, not the helper.
+
+module.exports = {
+  stripControlChars,
+  markInvisibleChars,
+  sanitizeRenderText,
+};