shakers-cli-beta 0.8.0-beta.0

package/bin/login.js

@@ -0,0 +1,283 @@
+#!/usr/bin/env node
+'use strict';
+
+// `login` / `logout` — a registered Talent identifies themselves to the CLI (talents-ai-score, issue 122 / ADR-044).
+
+const { detectReportLang, getCatalog } = require('../src/i18n');
+const { getLoginEndpoint, getAuthTokenEndpoint, getDeviceAuthorizeEndpoint, getDeviceTokenEndpoint, getCompleteRegistrationEndpoint } = require('../src/config');
+const { requestLogin } = require('../src/auth-client');
+const { runDeviceLogin, appendProviderParam } = require('../src/device-login');
+const { buildRegistrationContext } = require('../src/signup-client');
+const { openPath } = require('../src/open-file');
+const {
+  saveAuthSession,
+  clearAuthSession,
+  loadAuthSession,
+  sessionStatus,
+} = require('../src/auth-session-store');
+const { isValidEmail, normalizeEmail, loadConsentState, clearConsentState } = require('../src/share');
+const { createStdinAsk } = require('../src/stdin-ask');
+const { chooseAuthMethod } = require('../src/auth-method-picker');
+
+// Minimal flag parse: --email, --lang, --google, --linkedin, --provider.
+function parseArgs(argv) {
+  const opts = { email: null, lang: null, google: false, linkedin: false, provider: null };
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === '--email') opts.email = argv[++i];
+    else if (a.startsWith('--email=')) opts.email = a.slice('--email='.length);
+    else if (a === '--google') opts.google = true;
+    else if (a === '--linkedin') opts.linkedin = true;
+    else if (a === '--provider' && argv[i + 1] === 'google') { opts.google = true; opts.provider = 'google'; i++; }
+    else if (a === '--provider=google') { opts.google = true; opts.provider = 'google'; }
+    else if (a === '--provider' && argv[i + 1] === 'linkedin') { opts.linkedin = true; opts.provider = 'linkedin'; i++; }
+    else if (a === '--provider=linkedin') { opts.linkedin = true; opts.provider = 'linkedin'; }
+    else if (a === '--provider' && argv[i + 1] === 'email') { opts.provider = 'email'; i++; }
+    else if (a === '--provider=email') opts.provider = 'email';
+    else if (a === '--lang' && (argv[i + 1] === 'es' || argv[i + 1] === 'en')) opts.lang = argv[++i];
+    else if (a === '--lang=es') opts.lang = 'es';
+    else if (a === '--lang=en') opts.lang = 'en';
+  }
+  return opts;
+}
+
+function hasMethodFlag(opts) {
+  return opts.google || opts.linkedin || opts.provider === 'email' || !!opts.email;
+}
+
+// The interactive method picker for `login`.
+async function chooseLoginMethod({ ask, stdinIsTTY, c, input, output }) {
+  return chooseAuthMethod({ flow: 'login', ask, stdinIsTTY, catalog: c, input, output });
+}
+
+// The SECRET prompt (issue 102) — falls back to the ordinary line read on a pipe, which `ask()` still services.
+async function promptSecret(ask, label) {
+  const read = typeof ask.secret === 'function' ? ask.secret.bind(ask) : ask;
+  return String(await read(label)).trim();
+}
+
+async function resolveEmail(opts, c, ask) {
+  if (opts.email) return String(opts.email).trim();
+  for (let attempt = 0; attempt < 5; attempt++) {
+    const raw = String(await ask(c.emailPrompt)).trim();
+    if (raw === '') return null; // EOF / empty line / cancel
+    if (isValidEmail(raw)) return raw;
+    process.stdout.write(`  ${c.emailInvalid}\n`);
+  }
+  return null;
+}
+
+async function run(
+  argv = process.argv.slice(2),
+  { ask: injectedAsk = null, openBrowser = undefined, stdinIsTTY: ttyOverride = undefined, input = undefined, output = undefined, sleep = undefined } = {},
+) {
+  const opts = parseArgs(argv);
+  const lang = opts.lang || detectReportLang();
+  const c = getCatalog(lang).login;
+
+  if (opts.google) return runSocial('google', c, { openBrowser, sleep, lang });
+  if (opts.linkedin) return runSocial('linkedin', c, { openBrowser, sleep, lang });
+
+  // No method flag: offer the picker (ADR-041/046 — Email and Google only, LinkedIn stays parked).
+  if (!hasMethodFlag(opts)) {
+    const stdinIsTTY = ttyOverride !== undefined ? ttyOverride : !!process.stdin.isTTY;
+    if (stdinIsTTY) {
+      if (sessionStatus(loadAuthSession()) === 'active') {
+        process.stdout.write(`\n  ${c.alreadyLoggedIn}\n\n`);
+        return;
+      }
+      const pickerAsk = injectedAsk || createStdinAsk();
+      let method;
+      try {
+        method = await chooseLoginMethod({ ask: pickerAsk, stdinIsTTY, c, input, output });
+      } finally {
+        if (!injectedAsk) pickerAsk.close();
+      }
+      if (method === null) return; // esc/ctrl-c: cancelled, nothing sent
+      if (method === 'google' || method === 'linkedin') return runSocial(method, c, { openBrowser, sleep, lang });
+      // method === 'email' falls through to the unchanged flow below.
+    }
+  }
+
+  const endpoint = getLoginEndpoint();
+  if (!endpoint) {
+    process.stderr.write(`\n  ${c.errorNoEndpoint}\n\n`);
+    process.exitCode = 1;
+    return;
+  }
+
+  // ADR-044: an ACTIVE session is not silently overwritten — the Talent is told, and pointed at `logout` to switch accounts.
+  const status = sessionStatus(loadAuthSession());
+  if (status === 'active') {
+    process.stdout.write(`\n  ${c.alreadyLoggedIn}\n\n`);
+    return;
+  }
+  process.stdout.write(`\n  ${status === 'expired' ? c.sessionExpiredIntro : c.intro}\n`);
+
+  const ask = injectedAsk || createStdinAsk();
+  try {
+    const email = await resolveEmail(opts, c, ask);
+    if (!email || !isValidEmail(email)) {
+      process.stderr.write(`\n  ${c.needInput}\n\n`);
+      process.exitCode = 1;
+      return;
+    }
+    const password = await promptSecret(ask, c.passwordPrompt);
+    if (!password) {
+      process.stderr.write(`\n  ${c.needInput}\n\n`);
+      process.exitCode = 1;
+      return;
+    }
+
+    const normalizedEmail = normalizeEmail(email);
+    // better-auth email login: sign-in captures the session cookie, then a hub
+    // JWT is minted from it (auth-client.js). `endpoint` is the sign-in URL.
+    const result = await requestLogin(
+      { email: normalizedEmail, password },
+      { signInEndpoint: endpoint, tokenEndpoint: getAuthTokenEndpoint() },
+    );
+    handleResult(result, c, normalizedEmail);
+  } finally {
+    if (!injectedAsk) ask.close();
+  }
+}
+
+// Shared success path: persist the session (atomic 0600 store) and report.
+function persistAndReport(result, c, email = null) {
+  if (email) {
+    const prior = loadConsentState();
+    if (prior && prior.email && normalizeEmail(prior.email) !== normalizeEmail(email)) {
+      clearConsentState();
+    }
+  }
+  try {
+    // `cookie`/`cookieExpiresAt` are present for the email (better-auth) flow and
+    // absent for Google (auth-works JWT) — saveAuthSession picks the right model.
+    saveAuthSession({
+      accessToken: result.accessToken,
+      expiresAt: result.expiresAt,
+      accessTokenExpiresAt: result.expiresAt,
+      cookie: result.cookie || null,
+      cookieExpiresAt: result.cookieExpiresAt || null,
+      email,
+      hubAccessToken: result.hubAccessToken || null,
+    });
+  } catch {
+    process.stderr.write(`\n  ${c.errorPersist}\n\n`);
+    process.exitCode = 1;
+    return false;
+  }
+  process.stdout.write(`\n  ${c.success}\n`);
+  if (result.expiresAt) process.stdout.write(`  ${c.expiresAt(result.expiresAt)}\n`);
+  process.stdout.write('\n');
+  return true;
+}
+
+// `typedEmail` is what the CALLER typed/passed as `--email` for THIS attempt.
+function handleResult(result, c, typedEmail = null) {
+  if (result.ok) return void persistAndReport(result, c, result.email || typedEmail);
+
+  // One message per contract reason (ADR-044) — each names the cause (issue 109).
+  const messageFor = {
+    'invalid-credentials': c.errorInvalidCredentials,
+    'no-email-password': c.errorNoEmailPassword,
+    upstream: c.errorUpstream,
+    // Creds were good but the hub JWT could not be minted from the cookie.
+    'token-fetch-failed': c.errorUpstream,
+    timeout: c.errorUnreachable,
+    'network-error': c.errorUnreachable,
+    'invalid-url': c.errorConfig,
+    'no-endpoint': c.errorNoEndpoint,
+    'bad-response': c.errorGeneric,
+    'http-error': c.errorGeneric,
+    'local-error': c.errorGeneric,
+  };
+  process.stderr.write(`\n  ${messageFor[result.reason] || c.errorGeneric}\n\n`);
+  process.exitCode = 1;
+}
+
+// `login --google` / `--linkedin` — one device flow (RFC 8628); only the `provider` query on the URL differs.
+async function runSocial(provider, c, { openBrowser = openPath, sleep = undefined, lang = 'en' } = {}) {
+  const authorizeEndpoint = getDeviceAuthorizeEndpoint();
+  const tokenEndpoint = getDeviceTokenEndpoint();
+  const authTokenEndpoint = getAuthTokenEndpoint();
+  if (!authorizeEndpoint || !tokenEndpoint || !authTokenEndpoint) {
+    process.stderr.write(`\n  ${c.errorNoEndpoint}\n\n`);
+    process.exitCode = 1;
+    return;
+  }
+  // A new social account also needs complete-registration before the JWT (freelanceType is a transient default).
+  const completeRegistrationEndpoint = getCompleteRegistrationEndpoint();
+  const registrationContext = buildRegistrationContext({ preferredLanguage: lang, newsletterConsent: false, freelanceType: 'POTENTIAL_FREELANCE' });
+  const providerName = provider === 'linkedin' ? c.methodLinkedin : c.methodGoogle;
+
+  // Same as email: an ACTIVE session is not silently overwritten.
+  const status = sessionStatus(loadAuthSession());
+  if (status === 'active') {
+    process.stdout.write(`\n  ${c.alreadyLoggedIn}\n\n`);
+    return;
+  }
+  process.stdout.write(`\n  ${status === 'expired' ? c.sessionExpiredIntro : c.deviceIntro(providerName)}\n`);
+
+  const result = await runDeviceLogin(
+    { authorizeEndpoint, tokenEndpoint, authTokenEndpoint, completeRegistrationEndpoint, registrationContext },
+    {
+      ...(sleep ? { sleep } : {}),
+      onPrompt: ({ verificationUriComplete, userCode }) => {
+        const url = appendProviderParam(verificationUriComplete, provider);
+        process.stdout.write(`\n  ${c.deviceVisit}\n  ${url}\n\n  ${c.deviceCodeLabel(userCode)}\n\n  ${c.deviceWaiting}\n`);
+        try { openBrowser(url); } catch { /* the printed URL covers it */ }
+      },
+    },
+  );
+  handleSocialResult(result, c);
+}
+
+function handleSocialResult(result, c) {
+  if (result.ok) {
+    // Map the device-flow JWT to the shared persist shape (no cookie).
+    return void persistAndReport(
+      { accessToken: result.token, hubAccessToken: result.token, email: result.email || null },
+      c,
+      result.email || null,
+    );
+  }
+
+  const messageFor = {
+    expired: c.deviceErrorExpired,
+    denied: c.deviceErrorDenied,
+    'authorize-failed': c.deviceErrorGeneric,
+    'poll-failed': c.deviceErrorGeneric,
+    'token-exchange-failed': c.errorUpstream,
+    'complete-registration-failed': c.errorUpstream,
+    upstream: c.errorUpstream,
+    timeout: c.errorUnreachable,
+    'network-error': c.errorUnreachable,
+    'invalid-url': c.errorConfig,
+    'no-endpoint': c.errorNoEndpoint,
+    'bad-response': c.deviceErrorGeneric,
+    'http-error': c.deviceErrorGeneric,
+    'local-error': c.deviceErrorGeneric,
+  };
+  process.stderr.write(`\n  ${messageFor[result.reason] || c.deviceErrorGeneric}\n\n`);
+  process.exitCode = 1;
+}
+
+// `logout` — local only (no endpoint, no network): forget the stored session.
+async function runLogout(argv = process.argv.slice(2)) {
+  const opts = parseArgs(argv);
+  const lang = opts.lang || detectReportLang();
+  const c = getCatalog(lang).login;
+  const had = loadAuthSession() !== null;
+  clearAuthSession();
+  clearConsentState();
+  process.stdout.write(`\n  ${had ? c.loggedOut : c.notLoggedIn}\n\n`);
+}
+
+module.exports = { run, runLogout, chooseLoginMethod, parseArgs, hasMethodFlag };
+
+if (require.main === module) {
+  const argv = process.argv.slice(2);
+  if (argv[0] === 'logout') runLogout(argv.slice(1));
+  else run(argv);
+}

package/bin/mcp.js

@@ -0,0 +1,98 @@
+#!/usr/bin/env node
+'use strict';
+
+const { createMcpServer } = require('../src/mcp-server');
+const { makeAiUsageTool } = require('../src/mcp-ai-usage-tool');
+const { makeAiUsageResultTool } = require('../src/mcp-ai-usage-result-tool');
+const { makeCertifyDimensionTools } = require('../src/mcp-certify-dimension-tools');
+const { makeFindProjectsTools } = require('../src/mcp-find-projects-tools');
+const { makeShowProjectTools } = require('../src/mcp-show-project-tools');
+const { makeSavedPositionsTools } = require('../src/mcp-saved-positions-tools');
+const { makeInvitationsTools } = require('../src/mcp-invitations-tools');
+const { makeApplicationsTools } = require('../src/mcp-applications-tools');
+const { makeAvailabilityTools } = require('../src/mcp-availability-tools');
+const { makeCertificationsTools } = require('../src/mcp-certifications-tools');
+const { makeProfileTools } = require('../src/mcp-profile-tools');
+const { makeRateTools } = require('../src/mcp-rate-tools');
+const { makeAskTools } = require('../src/mcp-ask-tools');
+const { makeAlmaTools } = require('../src/mcp-alma-tools');
+const { makeLangTools } = require('../src/mcp-lang-tools');
+const { makeSocialsTools } = require('../src/mcp-socials-tools');
+const { makePortfolioTools } = require('../src/mcp-portfolios-tools');
+const { makeOnboardingTools } = require('../src/mcp-onboarding-tools');
+const { makeRoleTools } = require('../src/mcp-role-tools');
+const { makeDeviceLoginTools } = require('../src/mcp-device-login-tools');
+const { makeRegisterTools } = require('../src/mcp-register-tools');
+const { detectFlowLang } = require('../src/i18n');
+const { makeReportTools } = require('../src/mcp-report-tools');
+const { ensureFreshSession } = require('../src/session-refresh');
+
+let VERSION = '';
+try {
+  VERSION = require('../package.json').version || '';
+} catch {
+  VERSION = '';
+}
+
+const HELP = `\n  shakers mcp — local MCP server (stdio)\n\n`
+  + `  Exposes the AI-usage evaluation as an MCP tool over stdin/stdout so a\n`
+  + `  desktop AI app (Claude / ChatGPT Desktop) can run it on your machine.\n\n`
+  + `  Usage: shakers mcp\n\n`
+  + `  This command speaks JSON-RPC on stdio; it is meant to be launched by an\n`
+  + `  MCP client, not run by hand.\n`
+  + `  Tools: ai_usage, ai_usage_result, login, logout, social_signin_start, social_signin_poll,\n`
+  + `         list_addable, add_skill, add_agent,\n`
+  + `         add_project, register, register_status, onboarding_interview_start,\n`
+  + `         onboarding_interview_turn, onboarding_interview_complete,\n`
+  + `         repeat_onboarding_interview, onboarding_finish,\n`
+  + `         list_available_roles, add_role, list_my_roles, set_main_role,\n`
+  + `         report, share,\n`
+  + `         list_certifiable_dimensions, find_projects, show_project,\n`
+  + `         save_project, unsave_project, list_invitations,\n`
+  + `         list_applications, get_availability,\n`
+  + `         list_certifications, get_profile, get_rate, get_languages,\n`
+  + `         list_socials, list_experiences, list_portfolios, ask.\n\n`;
+
+function buildServer() {
+  return createMcpServer({
+    tools: [makeAiUsageTool(), makeAiUsageResultTool(), ...makeOnboardingTools(), ...makeRoleTools(), ...makeDeviceLoginTools(), ...makeRegisterTools({ lang: detectFlowLang() }), ...makeReportTools(), ...makeCertifyDimensionTools(), ...makeFindProjectsTools(), ...makeShowProjectTools(), ...makeSavedPositionsTools(), ...makeInvitationsTools(), ...makeApplicationsTools(), ...makeAvailabilityTools(), ...makeCertificationsTools(), ...makeProfileTools(), ...makeRateTools(), ...makeLangTools(), ...makeSocialsTools(), ...makePortfolioTools(), ...makeAskTools(), ...makeAlmaTools()],
+    serverInfo: { name: 'Shakers', version: VERSION || '0.0.0' },
+    // Long-lived server: refresh the email session's hub JWT from the stored
+    // cookie before each tool call so a stale (~15-min) JWT never reaches a tool.
+    beforeCall: () => ensureFreshSession(process.env),
+  });
+}
+
+async function run(argv = process.argv.slice(2)) {
+  // The installer's last step; not a command the Talent needs to know.
+  if (argv[0] === 'install') {
+    await require('../src/mcp-install').runMcpInstall();
+    return;
+  }
+  if (argv.includes('--help') || argv.includes('-h')) {
+    process.stdout.write(HELP);
+    return;
+  }
+
+  require('../src/config').ensureLocalConfigDefaults(process.env, { force: true });
+
+  const server = buildServer();
+  const rl = server.start({
+    input: process.stdin,
+    output: process.stdout,
+    onError: (e) => {
+      process.stderr.write(`  [mcp] ${e && e.message ? e.message : String(e)}\n`);
+    },
+  });
+
+  await new Promise((resolve) => {
+    rl.on('close', resolve);
+    process.stdin.on('end', () => rl.close());
+  });
+}
+
+module.exports = { run, buildServer };
+
+if (require.main === module) {
+  run();
+}

package/bin/me.js

@@ -0,0 +1,69 @@
+#!/usr/bin/env node
+'use strict';
+
+// `me` (alias `profile`) — talent summary: role + rate + "My work with AI".
+
+const { detectReportLang, getCatalog } = require('../src/i18n');
+const { loadAuthSession, sessionStatus } = require('../src/auth-session-store');
+const { createStdinAsk } = require('../src/stdin-ask');
+const { makeIo } = require('./register');
+const { makeRevealSink } = require('../src/reveal-output');
+const { runProfile, makeProfileDeps } = require('../src/profile-flow');
+
+function parseMeArgs(argv = []) {
+  const o = { lang: null, help: false, json: false };
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === '--help' || a === '-h') o.help = true;
+    else if (a === '--lang') { const v = argv[++i]; o.lang = v === 'es' || v === 'en' ? v : null; }
+    else if (a.startsWith('--lang=')) { const v = a.slice(7); o.lang = v === 'es' || v === 'en' ? v : null; }
+    else if (a === '--json') o.json = true;
+  }
+  return o;
+}
+
+async function run(
+  argv = process.argv.slice(2),
+  { ask: injectedAsk = null, stdinIsTTY: ttyOverride = undefined, deps = null, session: injectedSession = null, out = null } = {},
+) {
+  const opts = parseMeArgs(argv);
+  const lang = opts.lang || detectReportLang();
+  const catalog = getCatalog(lang);
+  const fp = catalog.profile;
+  const write = out || ((s) => process.stdout.write(s));
+
+  if (opts.help) {
+    write(fp.help + '\n');
+    return;
+  }
+
+  const session = injectedSession || loadAuthSession();
+  if (sessionStatus(session) !== 'active') {
+    process.stderr.write(`\n  ${fp.loginRequired}\n\n`);
+    process.exitCode = 1;
+    return;
+  }
+
+  const stdinIsTTY = ttyOverride !== undefined ? ttyOverride : !!process.stdin.isTTY;
+  const ask = injectedAsk || createStdinAsk();
+  const sink = makeRevealSink({ json: opts.json, interactive: false, out, env: process.env });
+  try {
+    const io = makeIo({ ask, lang, out: sink.write, stdinIsTTY });
+    const result = await runProfile({
+      io, rawOut: sink.write, session, catalog,
+      opts: { json: opts.json },
+      deps: deps || makeProfileDeps(),
+    });
+    await sink.finish();
+    if (result && result.ok === false) process.exitCode = 1;
+    return result;
+  } finally {
+    if (!injectedAsk) ask.close();
+  }
+}
+
+module.exports = { run, parseMeArgs };
+
+if (require.main === module) {
+  run();
+}

package/bin/onboarding.js

@@ -0,0 +1,134 @@
+#!/usr/bin/env node
+'use strict';
+
+const { detectFlowLang } = require('../src/i18n');
+const { loadAuthSession, sessionStatus } = require('../src/auth-session-store');
+const { createStdinAsk } = require('../src/stdin-ask');
+const { runOnboardingInterview, runRepeatOnboardingInterview, makeDeps } = require('../src/onboarding-flow');
+const { checkOnboardingCompleted } = require('../src/onboarding-availability');
+const { makeIo } = require('./register');
+const { c: fmt } = require('../src/terminal-format');
+const red = (s) => `${fmt.danger}${s}${fmt.reset}`;
+const yellow = (s) => `${fmt.warning}${s}${fmt.reset}`;
+
+const VALID_LANGS = new Set(['es', 'en']);
+
+const COPY = {
+  es: {
+    help: 'onboarding — solo la entrevista de onboarding de Shakers (requiere sesion). Uso: shakers onboarding [repeat] [--repeat] [--yes] [--lang es|en] [--accept-disclaimer]\n\n  repeat / --repeat  Repetir la entrevista SOBREESCRIBIENDO la anterior (pide confirmacion; --yes para confirmar sin TTY).',
+    gate: '"onboarding" requiere una sesion activa.\n  Falta: iniciar sesion. Ejecuta primero: shakers login',
+    missingAccept: 'Modo no interactivo: falta --accept-disclaimer.\n  onboarding es una entrevista interactiva.\n  Reejecuta con --accept-disclaimer, aportando las respuestas por stdin.',
+    alreadyPrompt: 'Ya completaste la entrevista de onboarding. ¿Quieres repetirla? (s/N)',
+    alreadyNeedFlag: 'Ya completaste la entrevista de onboarding.\n  Reejecutarla es opcional; si de verdad quieres repetirla, reejecuta con --confirm-repeat.',
+    alreadyAbort: 'De acuerdo, no se repite la entrevista de onboarding.',
+  },
+  en: {
+    help: 'onboarding — the Shakers onboarding interview only (requires a session). Usage: shakers onboarding [repeat] [--repeat] [--yes] [--lang es|en] [--accept-disclaimer]\n\n  repeat / --repeat  Repeat the interview OVERWRITING the previous one (asks for confirmation; --yes to confirm without a TTY).',
+    gate: '"onboarding" requires an active session.\n  Missing: sign-in. Run `shakers login` first.',
+    missingAccept: 'Non-interactive mode: --accept-disclaimer is missing.\n  onboarding is an interactive interview.\n  Re-run with --accept-disclaimer, feeding the answers over stdin.',
+    alreadyPrompt: 'You have already completed the onboarding interview. Do you want to repeat it? (y/N)',
+    alreadyNeedFlag: 'You have already completed the onboarding interview.\n  Re-running it is optional; if you really want to repeat it, re-run with --confirm-repeat.',
+    alreadyAbort: 'OK, not repeating the onboarding interview.',
+  },
+};
+
+function isYes(raw) {
+  const s = String(raw || '').trim().toLowerCase();
+  return s === 's' || s === 'si' || s === 'sí' || s === 'y' || s === 'yes';
+}
+
+function parseArgs(argv) {
+  const o = { lang: null, help: false, acceptDisclaimer: false, confirmRepeat: false, repeat: false, yes: false };
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === '--lang') o.lang = VALID_LANGS.has(argv[++i]) ? argv[i] : null;
+    else if (a.startsWith('--lang=')) { const v = a.slice(7); o.lang = VALID_LANGS.has(v) ? v : null; }
+    else if (a === '--accept-disclaimer') o.acceptDisclaimer = true;
+    else if (a === '--confirm-repeat') o.confirmRepeat = true;
+    else if (a === '--repeat' || a === 'repeat') o.repeat = true; // `shakers onboarding repeat` == --repeat
+    else if (a === '--yes' || a === '-y') o.yes = true;
+    else if (a === '--help' || a === '-h') o.help = true;
+  }
+  return o;
+}
+
+async function run(
+  argv = process.argv.slice(2),
+  { ask: injectedAsk = null, stdinIsTTY: ttyOverride = undefined, deps = null, out = null, session: injectedSession = null, checkCompleted = checkOnboardingCompleted } = {},
+) {
+  const o = parseArgs(argv);
+  const lang = o.lang || detectFlowLang();
+  const c = COPY[lang] || COPY.en;
+  const write = out || ((s) => process.stdout.write(s));
+
+  if (o.help) {
+    write(`\n  ${c.help}\n\n`);
+    return;
+  }
+
+  const session = injectedSession || loadAuthSession();
+  if (sessionStatus(session) !== 'active') {
+    process.stderr.write(`\n  ${red(c.gate)}\n\n`);
+    process.exitCode = 1;
+    return;
+  }
+
+  const stdinIsTTY = ttyOverride !== undefined ? ttyOverride : !!process.stdin.isTTY;
+
+  let completed = false;
+  try {
+    completed = await checkCompleted({ session });
+  } catch {
+    completed = false;
+  }
+
+  const ask = injectedAsk || createStdinAsk();
+  try {
+    // Explicit overwrite-repeat: its own warning + confirmation, bypassing the legacy already-completed gate.
+    if (o.repeat) {
+      const io = makeIo({ ask, lang, out: write, acceptDisclaimer: o.acceptDisclaimer, stdinIsTTY });
+      const result = await runRepeatOnboardingInterview(io, deps || makeDeps(), { confirmed: o.yes });
+      if (result && result.ok === false) {
+        process.stderr.write(`\n  ${red(`onboarding: ${result.reason}`)}\n\n`);
+        process.exitCode = 1;
+      }
+      return result;
+    }
+
+    if (completed && !o.confirmRepeat) {
+      const canPrompt = stdinIsTTY || !!injectedAsk;
+      if (!canPrompt) {
+        process.stderr.write(`\n  ${yellow(c.alreadyNeedFlag)}\n\n`);
+        process.exitCode = 1;
+        return;
+      }
+      const answer = await ask(`  ${c.alreadyPrompt} `);
+      if (!isYes(answer)) {
+        write(`\n  ${c.alreadyAbort}\n\n`);
+        return;
+      }
+    }
+
+    if (!stdinIsTTY && !o.acceptDisclaimer && !injectedAsk) {
+      process.stderr.write(`\n  ${red(c.missingAccept)}\n\n`);
+      process.exitCode = 1;
+      return;
+    }
+
+    const io = makeIo({ ask, lang, out: write, acceptDisclaimer: o.acceptDisclaimer, stdinIsTTY });
+    const result = await runOnboardingInterview(io, deps || makeDeps());
+    if (!result.ok) {
+      process.stderr.write(`\n  ${red(`onboarding: ${result.reason}${result.step ? ` (${result.step})` : ''}`)}\n\n`);
+      process.exitCode = 1;
+    }
+    return result;
+  } finally {
+    if (!injectedAsk) ask.close();
+  }
+}
+
+module.exports = { run, parseArgs };
+
+if (require.main === module) {
+  run();
+}

package/bin/portfolios.js

@@ -0,0 +1,69 @@
+#!/usr/bin/env node
+'use strict';
+
+// `portfolios` — the talent's portfolio showcase pieces (portfolios type=PORTFOLIO).
+
+const { detectReportLang, getCatalog } = require('../src/i18n');
+const { loadAuthSession, sessionStatus } = require('../src/auth-session-store');
+const { createStdinAsk } = require('../src/stdin-ask');
+const { makeIo } = require('./register');
+const { makeRevealSink } = require('../src/reveal-output');
+const { runPortfolioList, makePortfoliosDeps } = require('../src/portfolios-flow');
+
+function parseArgs(argv = []) {
+  const o = { lang: null, help: false, json: false };
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === '--help' || a === '-h') o.help = true;
+    else if (a === '--lang') { const v = argv[++i]; o.lang = v === 'es' || v === 'en' ? v : null; }
+    else if (a.startsWith('--lang=')) { const v = a.slice(7); o.lang = v === 'es' || v === 'en' ? v : null; }
+    else if (a === '--json') o.json = true;
+  }
+  return o;
+}
+
+async function run(
+  argv = process.argv.slice(2),
+  { ask: injectedAsk = null, stdinIsTTY: ttyOverride = undefined, deps = null, session: injectedSession = null, out = null } = {},
+) {
+  const opts = parseArgs(argv);
+  const lang = opts.lang || detectReportLang();
+  const catalog = getCatalog(lang);
+  const fp = catalog.portfolios;
+  const write = out || ((s) => process.stdout.write(s));
+
+  if (opts.help) {
+    write(fp.help + '\n');
+    return;
+  }
+
+  const session = injectedSession || loadAuthSession();
+  if (sessionStatus(session) !== 'active') {
+    process.stderr.write(`\n  ${fp.loginRequired}\n\n`);
+    process.exitCode = 1;
+    return;
+  }
+
+  const stdinIsTTY = ttyOverride !== undefined ? ttyOverride : !!process.stdin.isTTY;
+  const ask = injectedAsk || createStdinAsk();
+  const sink = makeRevealSink({ json: opts.json, out, env: process.env });
+  try {
+    const io = makeIo({ ask, lang, out: sink.write, stdinIsTTY });
+    const result = await runPortfolioList({
+      io, rawOut: sink.write, lang, session, catalog, kind: 'portfolios',
+      opts: { json: opts.json },
+      deps: deps || makePortfoliosDeps(),
+    });
+    await sink.finish();
+    if (result && result.ok === false) process.exitCode = 1;
+    return result;
+  } finally {
+    if (!injectedAsk) ask.close();
+  }
+}
+
+module.exports = { run, parseArgs };
+
+if (require.main === module) {
+  run();
+}