shakers-cli 0.0.0-stage → 0.14.1

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,112 @@
+'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,
+    // Hub's assigned-clusters rows name the role in clusterName.
+    name: typeof r.name === 'string' ? r.name : (typeof r.clusterName === 'string' ? r.clusterName : 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,
+    source: typeof r.source === 'string' ? r.source : null,
+  };
+}
+
+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) };
+}
+
+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) };
+}
+
+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 };
+}
+
+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,
+};

package/src/saved-positions-client.js

@@ -0,0 +1,71 @@
+'use strict';
+
+// Saved-positions client. Both
+// operations are idempotent server-side, so no read-before-write is needed.
+
+const { postJsonWithTimeout } = require('./backend-request');
+const { reasonForError } = require('./onboarding-client');
+
+const DEFAULT_TIMEOUT_MS = 20000;
+
+function bearerHeaders(accessToken) {
+  const headers = {};
+  if (typeof accessToken === 'string' && accessToken) headers.Authorization = `Bearer ${accessToken}`;
+  return headers;
+}
+
+async function requestSavePosition({ hubAccessToken } = {}, { positionId, endpoint, timeoutMs = DEFAULT_TIMEOUT_MS } = {}) {
+  if (!endpoint) return { ok: false, reason: 'no-endpoint' };
+  if (!positionId) return { ok: false, reason: 'no-id' };
+  if (!hubAccessToken) return { ok: false, reason: 'no-hub-token' };
+  let res;
+  try {
+    res = await postJsonWithTimeout(endpoint, { positionId }, timeoutMs, 'POST', null, bearerHeaders(hubAccessToken));
+  } catch (e) {
+    return { ok: false, reason: (e && e.kind) || 'network-error' };
+  }
+  if (res.status === 404) return { ok: false, reason: 'not-found' };
+  if (res.status < 200 || res.status >= 300) return { ok: false, reason: reasonForError(res.status, res.raw) };
+  return { ok: true };
+}
+
+async function requestUnsavePosition({ hubAccessToken } = {}, { positionId, endpoint, timeoutMs = DEFAULT_TIMEOUT_MS } = {}) {
+  if (!endpoint) return { ok: false, reason: 'no-endpoint' };
+  if (!positionId) return { ok: false, reason: 'no-id' };
+  if (!hubAccessToken) return { ok: false, reason: 'no-hub-token' };
+  let res;
+  try {
+    res = await postJsonWithTimeout(endpoint, null, timeoutMs, 'DELETE', 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 };
+}
+
+async function savePosition(deps = {}, { hubAccessToken, positionId, timeoutMs = DEFAULT_TIMEOUT_MS } = {}) {
+  const {
+    getSavePositionEndpoint = require('./config').getSavePositionEndpoint,
+    requestSavePosition: request = requestSavePosition,
+  } = deps;
+  const endpoint = getSavePositionEndpoint();
+  if (!endpoint) return { ok: false, reason: 'no-endpoint' };
+  return request({ hubAccessToken }, { positionId, endpoint, timeoutMs });
+}
+
+async function unsavePosition(deps = {}, { hubAccessToken, positionId, timeoutMs = DEFAULT_TIMEOUT_MS } = {}) {
+  const {
+    getUnsavePositionEndpoint = require('./config').getUnsavePositionEndpoint,
+    requestUnsavePosition: request = requestUnsavePosition,
+  } = deps;
+  const endpoint = getUnsavePositionEndpoint(positionId);
+  if (!endpoint) return { ok: false, reason: positionId ? 'no-endpoint' : 'no-id' };
+  return request({ hubAccessToken }, { positionId, endpoint, timeoutMs });
+}
+
+module.exports = {
+  requestSavePosition,
+  requestUnsavePosition,
+  savePosition,
+  unsavePosition,
+};

package/src/saved-positions-flow.js

@@ -0,0 +1,50 @@
+'use strict';
+
+// `save` / `unsave` flows: bookmark a Position. Reversible + idempotent, so no
+// confirmation (owner: low risk). Talent Bearer.
+
+function makeSavedPositionsDeps(overrides = {}) {
+  const client = require('./saved-positions-client');
+  return {
+    savePosition: (opts) => client.savePosition({}, opts),
+    unsavePosition: (opts) => client.unsavePosition({}, opts),
+    resolveRef: (raw) => require('./find-projects-cache').resolvePositionRef(raw),
+    ...overrides,
+  };
+}
+
+async function runToggleSave({ io, rawOut, session, catalog, mode, opts = {}, deps = makeSavedPositionsDeps() }) {
+  const fp = catalog.savedPositions;
+  const hubAccessToken = session ? session.hubAccessToken : null;
+  // A pure integer resolves against the last `find-projects` listing; a UUID/Mongo id passes through.
+  const resolved = deps.resolveRef(opts.id);
+  if (!resolved.ok) {
+    const idRequired = mode === 'save' ? fp.saveIdRequired : fp.unsaveIdRequired;
+    io.error(resolved.reason === 'no-cache' ? fp.refNoCache
+      : resolved.reason === 'out-of-range' ? fp.refOutOfRange(resolved.count)
+        : idRequired);
+    return { ok: false, reason: resolved.reason };
+  }
+  const positionId = resolved.id;
+
+  const label = mode === 'save' ? fp.saving : fp.unsaving;
+  const res = await io.withProgress(label, () => (mode === 'save'
+    ? deps.savePosition({ hubAccessToken, positionId })
+    : deps.unsavePosition({ hubAccessToken, positionId })));
+  if (!res.ok) {
+    io.error(res.reason === 'not-found' ? fp.notFound : fp.failed(res.reason));
+    return { ok: false, reason: res.reason };
+  }
+
+  if (opts.json) {
+    (rawOut || ((s) => process.stdout.write(s)))(`${JSON.stringify({ ok: true, mode, positionId }, null, 2)}\n`);
+    return { ok: true };
+  }
+  io.success(mode === 'save' ? fp.saved : fp.unsaved);
+  return { ok: true };
+}
+
+module.exports = {
+  makeSavedPositionsDeps,
+  runToggleSave,
+};

package/src/scan-exclusions.js

@@ -0,0 +1,50 @@
+'use strict';
+
+const path = require('path');
+
+// Directory names never descended into when walking a project tree (skill-code-certification, issue 008).
+const EXCLUDED_DIRS = new Set([
+  'node_modules', 'dist', 'build', '.git', 'vendor', 'coverage', '.next', 'out',
+  // Python
+  '__pycache__', '.venv', 'venv', '.tox', '.mypy_cache', '.pytest_cache', '.eggs',
+  // Ruby
+  '.bundle',
+  // Java / JVM (Gradle/Maven build output)
+  'target', '.gradle',
+]);
+
+const MAX_WALK_DEPTH = 8;
+
+const SYSTEM_ROOT_PATHS = new Set([
+  '/System', '/Library', '/Volumes', '/private', '/dev', '/proc',
+  '/opt', '/Applications', '/usr', '/bin', '/sbin', '/etc', '/var',
+  '/cores', '/Network',
+]);
+
+function normalizeWalkRoot(root) {
+  const resolved = path.resolve(root);
+  return resolved.length > 1 ? resolved.replace(/\/+$/, '') : resolved;
+}
+
+function isRefusedWalkRoot(root) {
+  if (typeof root !== 'string' || !root) return true;
+  let norm;
+  try {
+    norm = normalizeWalkRoot(root);
+  } catch {
+    return true;
+  }
+  return norm === '/' || SYSTEM_ROOT_PATHS.has(norm);
+}
+
+function isExcludedWalkPath(absDir) {
+  return SYSTEM_ROOT_PATHS.has(absDir);
+}
+
+module.exports = {
+  EXCLUDED_DIRS,
+  MAX_WALK_DEPTH,
+  SYSTEM_ROOT_PATHS,
+  isRefusedWalkRoot,
+  isExcludedWalkPath,
+};