shakers-cli 0.0.0-stage → 0.14.1

package/src/onboarding-funnel.js

@@ -0,0 +1,272 @@
+'use strict';
+
+const crypto = require('crypto');
+const fs = require('fs');
+const path = require('path');
+const { getConfigDir } = require('./config-dir');
+
+// Names and values mirror works-frontend onboarding-funnel-enums.ts.
+
+const FLOW_VERSION = 'signup_new_works_v1';
+
+const STEP_INDEX = Object.freeze({
+  start: 1,
+  account_creation: 2,
+  import_sources: 3,
+  work_situation: 4,
+  availability: 5,
+  rates: 6,
+  languages: 7,
+  location: 8,
+  profile_summary: 9,
+  pre_interview: 10,
+  interview: 11,
+  supercluster: 12,
+});
+
+const EVENT_TYPES = Object.freeze([
+  'onboarding_step_viewed',
+  'onboarding_step_completed',
+  'onboarding_step_skipped',
+  'onboarding_step_errored',
+  'onboarding_step_exited',
+  'source_import_started',
+  'source_import_completed',
+  'source_import_failed',
+]);
+
+const SURFACES = Object.freeze(['cli', 'mcp']);
+const MCP_CLIENTS = Object.freeze(['claude', 'chatgpt', 'cursor', 'other']);
+const SOURCE_TYPES = Object.freeze(['linkedin', 'cv', 'github', 'web_page']);
+const ERROR_TYPES = Object.freeze(['validation', 'server', 'timeout', 'auth', 'import']);
+
+const WORK_SITUATION_VALUES = Object.freeze({
+  FREELANCE: 'freelance',
+  EMPLOYED: 'employed',
+  BETWEEN_JOBS: 'between-jobs',
+  STUDYING: 'studying',
+  OTHER: 'other',
+});
+
+const ONCE_PER_STEP = new Set(['onboarding_step_viewed', 'onboarding_step_completed']);
+const MAX_EVENTS_PER_REQUEST = 50;
+const SEND_TIMEOUT_MS = 3000;
+const DEVICE_FILE_NAME = 'analytics-device.json';
+
+function mcpClientFor(clientName) {
+  const name = typeof clientName === 'string' ? clientName.toLowerCase() : '';
+  if (name.includes('claude')) return 'claude';
+  if (name.includes('chatgpt') || name.includes('openai')) return 'chatgpt';
+  if (name.includes('cursor')) return 'cursor';
+  return 'other';
+}
+
+function sourceTypeFor(source) {
+  if (source === 'linkedin' || source === 'cv' || source === 'github') return source;
+  return 'web_page';
+}
+
+function workSituationValue(code) {
+  return WORK_SITUATION_VALUES[code] || null;
+}
+
+// Same ÷4 as the web; '> 160' has no number.
+function weeklyHours(monthlyHours) {
+  const n = Number(monthlyHours);
+  return monthlyHours != null && monthlyHours !== '' && Number.isFinite(n) ? Math.round(n / 4) : null;
+}
+
+// As on the web: part-time project price is hourly, full-time is annual.
+function rateTypes({ partTimeSelected, fullTimeSelected } = {}) {
+  return [partTimeSelected === true && 'hourly', fullTimeSelected === true && 'annual'].filter(Boolean);
+}
+
+function errorTypeFor(reason) {
+  const r = String(reason || '');
+  if (r === 'no-session' || r === 'no-hub-token' || r === 'http-401' || r === 'http-403') return 'auth';
+  if (r === 'timeout') return 'timeout';
+  if (r === 'no-endpoint') return 'server';
+  if (r.startsWith('bad-') || r.startsWith('no-') || r === 'duplicate-language' || r === 'unresolved-languages') return 'validation';
+  return 'server';
+}
+
+function cleanProperties(properties) {
+  const ok = (v) => typeof v === 'string' || typeof v === 'boolean' || (typeof v === 'number' && Number.isFinite(v))
+    || (Array.isArray(v) && v.every((x) => typeof x === 'string'));
+  return Object.fromEntries(Object.entries(properties || {}).filter(([, v]) => ok(v)));
+}
+
+function deviceFilePath(env) {
+  return path.join(getConfigDir(env), DEVICE_FILE_NAME);
+}
+
+function loadOrCreateDeviceId(env = process.env, { fs: fsImpl = fs } = {}) {
+  const target = deviceFilePath(env);
+  try {
+    const parsed = JSON.parse(fsImpl.readFileSync(target, 'utf8'));
+    if (parsed && typeof parsed.deviceId === 'string' && parsed.deviceId) return parsed.deviceId;
+  } catch { /* create one */ }
+  const deviceId = crypto.randomUUID();
+  const dir = path.dirname(target);
+  const tmp = path.join(dir, `.${DEVICE_FILE_NAME}.${process.pid}.${crypto.randomBytes(6).toString('hex')}.tmp`);
+  let fd = null;
+  try {
+    fsImpl.mkdirSync(dir, { recursive: true, mode: 0o700 });
+    fd = fsImpl.openSync(tmp, 'wx', 0o600);
+    fsImpl.writeFileSync(fd, `${JSON.stringify({ deviceId }, null, 2)}\n`);
+    try { fsImpl.fsyncSync(fd); } catch { /* e.g. EINVAL on some filesystems */ }
+    fsImpl.closeSync(fd);
+    fd = null;
+    fsImpl.renameSync(tmp, target);
+    return deviceId;
+  } catch {
+    if (fd !== null) { try { fsImpl.closeSync(fd); } catch { /* already closed */ } }
+    try { fsImpl.unlinkSync(tmp); } catch { /* never existed */ }
+    return null;
+  }
+}
+
+async function defaultSend({ endpoint, events, hubAccessToken }) {
+  const { postJsonWithTimeout } = require('./backend-request');
+  const res = await postJsonWithTimeout(endpoint, { events }, SEND_TIMEOUT_MS, 'POST', null, { Authorization: `Bearer ${hubAccessToken}` });
+  return { ok: res.status >= 200 && res.status < 300, status: res.status };
+}
+
+function defaultHubToken() {
+  const { loadAuthSession, sessionStatus } = require('./auth-session-store');
+  const session = loadAuthSession();
+  return sessionStatus(session) === 'active' && session && session.hubAccessToken ? session.hubAccessToken : null;
+}
+
+function createFunnel({
+  surface,
+  hubToken = defaultHubToken,
+  deviceId = () => loadOrCreateDeviceId(),
+  endpoint = () => require('./config').getOnboardingEventsEndpoint(),
+  send = defaultSend,
+  now = () => Date.now(),
+  uuid = () => crypto.randomUUID(),
+} = {}) {
+  if (!SURFACES.includes(surface)) throw new Error(`unknown funnel surface: ${surface}`);
+  let pending = [];
+  let lastTime = 0;
+  let seq = 0;
+  let ready = false;
+  let account = null;
+  let active = false;
+  let mcpClient = null;
+  let cachedDeviceId;
+  const seen = new Set();
+  const inflight = new Set();
+
+  function track(eventType, stepName, properties = {}) {
+    if (!active || !EVENT_TYPES.includes(eventType) || !STEP_INDEX[stepName]) return false;
+    if (ONCE_PER_STEP.has(eventType)) {
+      const key = `${eventType}:${stepName}`;
+      if (seen.has(key)) return false;
+      seen.add(key);
+    }
+    const common = { step_name: stepName, step_index: STEP_INDEX[stepName], flow_version: FLOW_VERSION, surface };
+    if (surface === 'mcp') common.mcp_client = mcpClient || 'other';
+    pending.push({ eventType, insertId: uuid(), at: now(), seq: seq++, properties: { ...cleanProperties(properties), ...common } });
+    return true;
+  }
+
+  // Funnel order, each time strictly after the previous one sent.
+  function stamp(batch) {
+    const ordered = [...batch].sort((a, b) => a.properties.step_index - b.properties.step_index || a.seq - b.seq);
+    const id = cachedDeviceId === undefined ? (cachedDeviceId = safe(deviceId)) : cachedDeviceId;
+    return ordered.map((e) => {
+      lastTime = Math.max(e.at, lastTime + 1);
+      return { event_type: e.eventType, insert_id: e.insertId, time: lastTime, ...(id ? { device_id: id } : {}), properties: e.properties };
+    });
+  }
+
+  function flush() {
+    if (!ready || !pending.length) return Promise.resolve();
+    const token = safe(hubToken);
+    const url = safe(endpoint);
+    // Never send under another account signed in since.
+    if (!token || !url || accountOf(token) !== account) return Promise.resolve();
+    const events = stamp(pending);
+    pending = [];
+    const sends = [];
+    for (let i = 0; i < events.length; i += MAX_EVENTS_PER_REQUEST) {
+      sends.push(Promise.resolve().then(() => send({ endpoint: url, events: events.slice(i, i + MAX_EVENTS_PER_REQUEST), hubAccessToken: token })).catch(() => null));
+    }
+    const done = Promise.all(sends).then(() => undefined, () => undefined);
+    inflight.add(done);
+    done.then(() => inflight.delete(done));
+    return done;
+  }
+
+  return {
+    surface,
+    begin() {
+      seen.clear();
+      active = true;
+    },
+    get active() { return active; },
+    setMcpClient(clientName) { mcpClient = mcpClientFor(clientName); },
+    track,
+    viewed: (step, props) => track('onboarding_step_viewed', step, props),
+    completed: (step, props) => track('onboarding_step_completed', step, props),
+    skipped: (step, props) => track('onboarding_step_skipped', step, props),
+    errored: (step, reason, props = {}) => track('onboarding_step_errored', step, { error_type: errorTypeFor(reason), ...props }),
+    identified() {
+      const token = safe(hubToken);
+      if (!token) return Promise.resolve();
+      account = accountOf(token);
+      ready = true;
+      return flush();
+    },
+    flush,
+    idle: () => Promise.all([...inflight]).then(() => undefined),
+  };
+}
+
+// A refreshed token keeps the same account.
+function accountOf(token) {
+  const payload = require('./auth-session-store').decodeJwtPayload(token);
+  return (payload && (payload.sub || payload.email)) || token;
+}
+
+function safe(fn) {
+  try { return fn(); } catch { return null; }
+}
+
+const NOOP_FUNNEL = Object.freeze({
+  surface: null,
+  begin() {},
+  active: false,
+  setMcpClient() {},
+  track: () => false,
+  viewed: () => false,
+  completed: () => false,
+  skipped: () => false,
+  errored: () => false,
+  identified: () => Promise.resolve(),
+  flush: () => Promise.resolve(),
+  idle: () => Promise.resolve(),
+});
+
+module.exports = {
+  FLOW_VERSION,
+  STEP_INDEX,
+  EVENT_TYPES,
+  SURFACES,
+  MCP_CLIENTS,
+  SOURCE_TYPES,
+  ERROR_TYPES,
+  MAX_EVENTS_PER_REQUEST,
+  DEVICE_FILE_NAME,
+  NOOP_FUNNEL,
+  createFunnel,
+  mcpClientFor,
+  sourceTypeFor,
+  workSituationValue,
+  weeklyHours,
+  rateTypes,
+  errorTypeFor,
+  loadOrCreateDeviceId,
+};

package/src/onboarding-livekit-client.js

@@ -0,0 +1,102 @@
+'use strict';
+
+// Thin certs adapter: exchange a created onboarding interview for LiveKit room credentials so the CLI can join over text (lk.chat).
+
+const { postJsonWithTimeout } = require('./backend-request');
+const { reasonForError } = require('./onboarding-client');
+const { toUpperLang } = require('./lang-codes');
+
+const DEFAULT_TIMEOUT_MS = 20000;
+// Sub-path appended to `{base}/{interviewId}/` — the real post-merge certs
+// route (sibling of `text-session`). Change this ONE constant if it moves.
+const LIVEKIT_SESSION_PATH = 'livekit-text-session';
+// Completion route: `PATCH {base}/{interviewId}/complete`.
+const COMPLETE_SESSION_PATH = 'complete';
+
+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' || json.status !== 'OK') return undefined;
+  return json.data;
+}
+
+function bearerHeaders(accessToken) {
+  const headers = {};
+  if (typeof accessToken === 'string' && accessToken) headers.Authorization = `Bearer ${accessToken}`;
+  return headers;
+}
+
+function pickString(obj, keys) {
+  for (const k of keys) {
+    const v = obj && obj[k];
+    if (typeof v === 'string' && v) return v;
+  }
+  return null;
+}
+
+async function requestStartOnboardingLivekitSession(
+  { interviewId, language, accessToken } = {},
+  { base, path = LIVEKIT_SESSION_PATH, timeoutMs = DEFAULT_TIMEOUT_MS } = {},
+) {
+  if (!base) return { ok: false, reason: 'no-endpoint' };
+  if (!interviewId) return { ok: false, reason: 'no-interview' };
+
+  const url = `${base.replace(/\/+$/, '')}/${encodeURIComponent(interviewId)}/${path}`;
+  const body = { language: toUpperLang(language) };
+  let res;
+  try {
+    res = await postJsonWithTimeout(url, body, timeoutMs, 'POST', null, bearerHeaders(accessToken));
+  } 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);
+  if (data === undefined || !data || typeof data !== 'object') return { ok: false, reason: 'bad-response' };
+
+  const livekitUrl = pickString(data, ['livekitUrl', 'url', 'wsUrl', 'serverUrl']);
+  const token = pickString(data, ['token', 'accessToken', 'participantToken']);
+  const roomName = pickString(data, ['roomName', 'room', 'room_name']);
+  const closingMessage = pickString(data, ['closingMessage', 'closing']);
+  const resolvedId = pickString(data, ['interviewId', 'id']) || interviewId;
+
+  if (!livekitUrl || !token) return { ok: false, reason: 'bad-response' };
+  return { ok: true, livekitUrl, token, roomName: roomName || null, interviewId: resolvedId, closingMessage: closingMessage || null };
+}
+
+// Persist the onboarding interview's transcript on session end (the LiveKit text flow is the one path that was not sending it; certs already stores + serves it).
+async function requestCompleteOnboardingLivekitSession(
+  { interviewId, durationSeconds, transcripts, accessToken } = {},
+  { base, path = COMPLETE_SESSION_PATH, timeoutMs = DEFAULT_TIMEOUT_MS } = {},
+) {
+  if (!base) return { ok: false, reason: 'no-endpoint' };
+  if (!interviewId) return { ok: false, reason: 'no-interview' };
+  if (!Array.isArray(transcripts) || transcripts.length === 0) return { ok: false, reason: 'no-transcript' };
+
+  const url = `${base.replace(/\/+$/, '')}/${encodeURIComponent(interviewId)}/${path}`;
+  const body = { transcripts };
+  if (Number.isInteger(durationSeconds) && durationSeconds >= 0) body.durationSeconds = durationSeconds;
+
+  let res;
+  try {
+    res = await postJsonWithTimeout(url, body, timeoutMs, 'PATCH', null, bearerHeaders(accessToken));
+  } 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 };
+}
+
+module.exports = {
+  requestStartOnboardingLivekitSession,
+  requestCompleteOnboardingLivekitSession,
+  LIVEKIT_SESSION_PATH,
+  COMPLETE_SESSION_PATH,
+};

package/src/onboarding-status-client.js

@@ -0,0 +1,57 @@
+'use strict';
+
+const { postJsonWithTimeout } = require('./backend-request');
+
+const DEFAULT_TIMEOUT_MS = 12000;
+
+function parseJson(raw) {
+  try {
+    return raw ? JSON.parse(raw) : null;
+  } catch {
+    return null;
+  }
+}
+
+function authHeaders({ accessToken } = {}) {
+  const headers = {};
+  if (typeof accessToken === 'string' && accessToken) headers.Authorization = `Bearer ${accessToken}`;
+  return headers;
+}
+
+async function requestOnboardingStatus({ accessToken } = {}, { endpoint, timeoutMs = DEFAULT_TIMEOUT_MS } = {}) {
+  if (!endpoint) return { ok: false, reason: 'no-endpoint' };
+
+  let res;
+  try {
+    res = await postJsonWithTimeout(endpoint, null, timeoutMs, 'GET', null, authHeaders({ accessToken }));
+  } catch (e) {
+    return { ok: false, reason: (e && e.kind) || 'network-error' };
+  }
+
+  if (res.status < 200 || res.status >= 300) {
+    return { ok: false, reason: `http-${res.status}` };
+  }
+
+  const json = parseJson(res.raw);
+  const data = json && typeof json === 'object' ? json.data : null;
+  if (!data || typeof data !== 'object') return { ok: false, reason: 'bad-response' };
+
+  return { ok: true, completed: data.completed === true };
+}
+
+// GET <certs>/interviews/:id/finalization -> COLLECTING | PROCESSING | READY | FAILED for a completed interview's evaluation.
+async function requestInterviewFinalization({ interviewId, accessToken } = {}, { base, timeoutMs = DEFAULT_TIMEOUT_MS } = {}) {
+  if (!base || !interviewId) return { ok: false, reason: 'no-endpoint' };
+  let res;
+  try {
+    res = await postJsonWithTimeout(`${base}/${encodeURIComponent(interviewId)}/finalization`, null, timeoutMs, 'GET', null, authHeaders({ accessToken }));
+  } catch (e) {
+    return { ok: false, reason: (e && e.kind) || 'network-error' };
+  }
+  if (res.status < 200 || res.status >= 300) return { ok: false, reason: `http-${res.status}` };
+  const json = parseJson(res.raw);
+  const status = json && json.data && typeof json.data.status === 'string' ? json.data.status : null;
+  return status ? { ok: true, status } : { ok: false, reason: 'bad-response' };
+}
+
+module.exports = { requestOnboardingStatus, requestInterviewFinalization };

package/src/open-file.js

@@ -0,0 +1,32 @@
+'use strict';
+
+const { spawn } = require('child_process');
+
+// Zero-dependency, best-effort "open this file in the OS default app" (ADR-016, used by the `report` command to open the generated HTML in the browser).
+function openPath(target) {
+  let cmd;
+  let args;
+  if (process.platform === 'darwin') {
+    cmd = 'open';
+    args = [target];
+  } else if (process.platform === 'win32') {
+    // `start` needs an (empty) title arg first when the target may be quoted.
+    cmd = 'cmd';
+    args = ['/c', 'start', '', target];
+  } else {
+    cmd = 'xdg-open';
+    args = [target];
+  }
+  try {
+    const child = spawn(cmd, args, { stdio: 'ignore', detached: true });
+    // An absent opener (ENOENT) surfaces as an async 'error' — swallow it so it
+    // never becomes an unhandled exception that breaks the REPL.
+    child.on('error', () => {});
+    child.unref();
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+module.exports = { openPath };

package/src/osc-link.js

@@ -0,0 +1,16 @@
+'use strict';
+
+// OSC 8 terminal hyperlink helper (talents-ai-score, user request: links were printed as plain text and could NOT be clicked in iTerm2).
+
+const OSC = '\x1b]8;;';
+const ST = '\x1b\\';
+
+// Wrap `label` as an OSC 8 hyperlink to `url`.
+function oscLink(url, label) {
+  const target = url == null ? '' : String(url);
+  const text = label == null || label === '' ? target : String(label);
+  if (!target) return text;
+  return `${OSC}${target}${ST}${text}${OSC}${ST}`;
+}
+
+module.exports = { oscLink };

package/src/portfolio-client.js

@@ -0,0 +1,164 @@
+'use strict';
+
+const { postJsonWithTimeout, postMultipartWithTimeout } = require('./backend-request');
+const { reasonForError, WORKS_CODE_TO_REASON } = require('./skills-client');
+
+// Talent-portfolio client (talents-ai-score, ADR-059 — `start`'s "Add project to portfolio" route, src/start-add-portfolio.js).
+
+const DEFAULT_TIMEOUT_MS = 20000;
+
+function parseJson(raw) {
+  try {
+    return raw ? JSON.parse(raw) : null;
+  } catch {
+    return null;
+  }
+}
+
+function authHeaders({ accessToken, hubAccessToken } = {}) {
+  const headers = {};
+  if (typeof accessToken === 'string' && accessToken) headers.Authorization = `Bearer ${accessToken}`;
+  if (typeof hubAccessToken === 'string' && hubAccessToken) headers['X-Hub-Token'] = hubAccessToken;
+  return headers;
+}
+
+function hubHeaders({ hubAccessToken } = {}) {
+  const headers = {};
+  if (typeof hubAccessToken === 'string' && hubAccessToken) headers.Authorization = `Bearer ${hubAccessToken}`;
+  return headers;
+}
+
+// `GET .../portfolios`.
+async function requestListPortfolios({ accessToken, 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, authHeaders({ accessToken, 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 json = parseJson(res.raw);
+  const data = json && typeof json === 'object' && Array.isArray(json.data) ? json.data : null;
+  if (!data) return { ok: false, reason: 'bad-response' };
+
+  const portfolios = data
+    .map((entry) => ({
+      id: entry && typeof entry.id === 'string' ? entry.id : null,
+      name: entry && typeof entry.name === 'string' ? entry.name : null,
+      type: entry && typeof entry.type === 'string' ? entry.type : null,
+      skillIds: entry && Array.isArray(entry.skillIds) ? entry.skillIds : [],
+      startDate: entry && typeof entry.startDate === 'string' ? entry.startDate : null,
+      endDate: entry && typeof entry.endDate === 'string' ? entry.endDate : null,
+      isCurrent: entry ? entry.isCurrent === true : false,
+    }))
+    .filter((p) => p.name !== null);
+  return { ok: true, portfolios };
+}
+
+// `POST .../portfolios/declare`.
+async function requestDeclarePortfolio(
+  { name, type, skillIds, description, url, clientName, clientDomain, startDate, endDate, accessToken, hubAccessToken } = {},
+  { endpoint, timeoutMs = DEFAULT_TIMEOUT_MS } = {},
+) {
+  if (!endpoint) return { ok: false, reason: 'no-endpoint' };
+  if (!hubAccessToken) return { ok: false, reason: 'no-hub-token' };
+
+  const body = { name, type };
+  if (Array.isArray(skillIds) && skillIds.length > 0) body.skillIds = skillIds;
+  if (typeof description === 'string' && description) body.description = description;
+  if (typeof url === 'string' && url) body.url = url;
+  if (typeof clientName === 'string' && clientName) body.clientName = clientName;
+  if (typeof clientDomain === 'string' && clientDomain) body.clientDomain = clientDomain;
+  if (typeof startDate === 'string' && startDate) body.startDate = startDate;
+  if (typeof endDate === 'string' && endDate) body.endDate = endDate;
+  body.generatedWith = 'AI';
+
+  let res;
+  try {
+    res = await postJsonWithTimeout(endpoint, body, timeoutMs, 'POST', null, authHeaders({ accessToken, 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 json = parseJson(res.raw);
+  if (!json || json.status !== 'OK') return { ok: false, reason: 'bad-response' };
+  return { ok: true };
+}
+
+// `POST .../portfolios/draft-description`.
+async function requestDraftDescription(
+  { name, technologies, readme, packageDescription, accessToken } = {},
+  { endpoint, timeoutMs = DEFAULT_TIMEOUT_MS } = {},
+) {
+  if (!endpoint) return { ok: false, reason: 'no-endpoint' };
+
+  const body = {
+    consent: true,
+    name,
+    technologies: Array.isArray(technologies) ? technologies.filter((t) => typeof t === 'string' && t) : [],
+  };
+  if (typeof readme === 'string' && readme) body.readme = readme;
+  if (typeof packageDescription === 'string' && packageDescription) body.packageDescription = packageDescription;
+
+  let res;
+  try {
+    res = await postJsonWithTimeout(endpoint, body, timeoutMs, 'POST', null, authHeaders({ accessToken }));
+  } 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 json = parseJson(res.raw);
+  const description = json && json.status === 'OK' && json.data && typeof json.data.description === 'string'
+    ? json.data.description
+    : null;
+  if (!description) return { ok: false, reason: 'bad-response' };
+  return { ok: true, description };
+}
+
+async function requestUpdatePortfolioSkills(
+  { portfolioId, skillIds, hubAccessToken } = {},
+  { endpoint, timeoutMs = DEFAULT_TIMEOUT_MS } = {},
+) {
+  if (!endpoint) return { ok: false, reason: 'no-endpoint' };
+  if (!hubAccessToken) return { ok: false, reason: 'no-hub-token' };
+  if (!portfolioId) return { ok: false, reason: 'no-portfolio' };
+
+  const url = `${endpoint.replace(/\/+$/, '')}/${encodeURIComponent(portfolioId)}`;
+  const fields = { skillIds: (Array.isArray(skillIds) ? skillIds : []).join(',') };
+  let res;
+  try {
+    res = await postMultipartWithTimeout(url, fields, timeoutMs, 'PATCH', hubHeaders({ 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 json = parseJson(res.raw);
+  if (!json || json.status !== 'OK') return { ok: false, reason: 'bad-response' };
+  return { ok: true };
+}
+
+module.exports = {
+  requestListPortfolios,
+  requestDeclarePortfolio,
+  requestDraftDescription,
+  requestUpdatePortfolioSkills,
+  WORKS_CODE_TO_REASON,
+};