shakers-cli 0.0.0-stage → 0.14.1

package/bin/login.js

@@ -0,0 +1,216 @@
+#!/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 { getAuthTokenEndpoint, getDeviceAuthorizeEndpoint, getDeviceTokenEndpoint, getCompleteRegistrationEndpoint } = require('../src/config');
+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 { 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 });
+}
+
+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;
+
+  // Every method signs in through the real web device flow (RFC 8628): the
+  // Talent reuses an existing web session or signs in on the `/cli-login` page,
+  // so no password is ever read in the terminal. Email now travels the same
+  // path Google/LinkedIn already use; only the `provider` query differs.
+  let method = null;
+  if (opts.google) method = 'google';
+  else if (opts.linkedin) method = 'linkedin';
+  else if (opts.provider === 'email' || !!opts.email) method = 'email';
+
+  if (!method) {
+    const stdinIsTTY = ttyOverride !== undefined ? ttyOverride : !!process.stdin.isTTY;
+    // ADR-044: an ACTIVE session is not silently overwritten, and the picker never shows.
+    if (sessionStatus(loadAuthSession()) === 'active') {
+      (output || process.stdout).write(`\n  ${c.alreadyLoggedIn}\n\n`);
+      return;
+    }
+    if (stdinIsTTY) {
+      // ADR-041/046 — the picker offers Email, Google and LinkedIn.
+      const pickerAsk = injectedAsk || createStdinAsk();
+      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
+    } else {
+      method = 'email'; // non-interactive default (matches the picker's own non-TTY default)
+    }
+  }
+
+  return runDeviceFlow(method, c, { openBrowser, sleep, lang, output });
+}
+
+// Shared success path: persist the session (atomic 0600 store) and report.
+// `output` lets a caller (and tests) redirect the human-facing lines; errors stay on stderr.
+function persistAndReport(result, c, email = null, output = process.stdout) {
+  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;
+  }
+  output.write(`\n  ${c.success}\n`);
+  if (result.expiresAt) output.write(`  ${c.expiresAt(result.expiresAt)}\n`);
+  output.write('\n');
+  return true;
+}
+
+// `login` for one method — one device flow (RFC 8628); only the `provider` query
+// on the `/cli-login` URL differs (google | linkedin | email). Email reuses an
+// existing web session or signs in on the page, with no password in the terminal.
+async function runDeviceFlow(provider, c, { openBrowser = openPath, sleep = undefined, lang = 'en', output = process.stdout } = {}) {
+  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 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 : provider === 'email' ? c.methodEmail : c.methodGoogle;
+
+  // An ACTIVE session is not silently overwritten.
+  const status = sessionStatus(loadAuthSession());
+  if (status === 'active') {
+    output.write(`\n  ${c.alreadyLoggedIn}\n\n`);
+    return;
+  }
+  const intro = status === 'expired'
+    ? c.sessionExpiredIntro
+    : (provider === 'email' ? c.emailDeviceIntro : c.deviceIntro(providerName));
+  output.write(`\n  ${intro}\n`);
+
+  const result = await runDeviceLogin(
+    { authorizeEndpoint, tokenEndpoint, authTokenEndpoint, completeRegistrationEndpoint, registrationContext },
+    {
+      ...(sleep ? { sleep } : {}),
+      onPrompt: ({ verificationUriComplete, userCode }) => {
+        const url = appendProviderParam(verificationUriComplete, provider);
+        output.write(`\n  ${c.deviceVisit}\n  ${url}\n\n  ${c.deviceCodeLabel(userCode)}\n\n  ${c.deviceWaiting}\n`);
+        if (provider === 'email') output.write(`  ${c.deviceApproveHint}\n`);
+        try { openBrowser(url); } catch { /* the printed URL covers it */ }
+      },
+    },
+  );
+  handleDeviceResult(result, c, output);
+}
+
+function handleDeviceResult(result, c, output = process.stdout) {
+  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,
+      output,
+    );
+  }
+
+  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), { output = process.stdout } = {}) {
+  const opts = parseArgs(argv);
+  const lang = opts.lang || detectReportLang();
+  const c = getCatalog(lang).login;
+  const had = loadAuthSession() !== null;
+  clearAuthSession();
+  clearConsentState();
+  output.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,124 @@
+#!/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 { 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 { makeSignupTools } = require('../src/mcp-signup-tools');
+const { detectFlowLang } = require('../src/i18n');
+const { makeReportTools } = require('../src/mcp-report-tools');
+const { makePrompts } = require('../src/mcp-prompts');
+const { buildServerInstructions } = require('../src/mcp-instructions');
+const { ensureFreshSession } = require('../src/session-refresh');
+const { createFunnel } = require('../src/onboarding-funnel');
+
+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, logout, social_signin_start, social_signin_poll,\n`
+  + `         list_addable, add_skill, add_agent,\n`
+  + `         add_project, signup_start, signup_email, signup_draft, signup_create_account,\n`
+  + `         signup_status, update_existing_profile, import_profile, save_profile_details, open_web,\n`
+  + `         open_linkedin_profile,\n`
+  + `         suggest_register_context, read_cv, 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, alma_chat, alma_decision.\n\n`;
+
+// The LOCAL (filesystem/machine) tools — the only ones the .mcpb bundle exposes; the
+// server-backed tools belong to the remote connector.
+const LOCAL_ONLY_TOOL_NAMES = new Set(['ai_usage', 'ai_usage_result', 'read_cv', 'suggest_register_context']);
+
+// `localOnly` builds the scan-only server for the Claude .mcpb bundle, reusing the SAME
+// tool registry (just filtered) — no duplicate registration.
+function buildServer({ localOnly = false, funnel = createFunnel({ surface: 'mcp' }) } = {}) {
+  const lang = detectFlowLang();
+  const allTools = [makeAiUsageTool(), makeAiUsageResultTool(), ...makeOnboardingTools(), ...makeRoleTools({ lang, funnel }), ...makeDeviceLoginTools(), ...makeSignupTools({ lang, funnel }), ...makeRegisterTools({ lang, funnel }), ...makeReportTools(), ...makeCertifyDimensionTools(), ...makeFindProjectsTools(), ...makeShowProjectTools(), ...makeSavedPositionsTools(), ...makeInvitationsTools(), ...makeApplicationsTools(), ...makeAvailabilityTools(), ...makeCertificationsTools(), ...makeProfileTools(), ...makeRateTools(), ...makeLangTools(), ...makeSocialsTools(), ...makePortfolioTools(), ...makeAlmaTools()];
+  const tools = localOnly ? allTools.filter((t) => LOCAL_ONLY_TOOL_NAMES.has(t.name)) : allTools;
+  // Slash-command prompts, kept to the tools actually registered in this mode.
+  const prompts = makePrompts(new Set(tools.map((t) => t.name)), lang);
+  return createMcpServer({
+    tools,
+    prompts,
+    serverInfo: { name: localOnly ? 'Shakers (local scan)' : 'Shakers', version: VERSION || '0.0.0' },
+    instructions: localOnly ? null : (client) => buildServerInstructions(client),
+    // 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),
+    onInitialize: ({ clientInfo }) => funnel.setMcpClient(clientInfo.name),
+  });
+}
+
+function prepareProcess(env = process.env) {
+  require('../src/config').sanitizeStaleBakedEndpoints(env);
+  require('../src/backend-request').setClientIdentity('mcp');
+}
+
+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;
+  }
+
+  prepareProcess();
+
+  // `--local` = the scan-only server shipped in the Claude .mcpb bundle.
+  const server = buildServer({ localOnly: argv.includes('--local') });
+  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, buildServerInstructions, prepareProcess };
+
+if (require.main === module) {
+  run();
+}

package/bin/mcpb.js

@@ -0,0 +1,5 @@
+#!/usr/bin/env node
+'use strict';
+
+// Claude Desktop's built-in Node imports this entry from its own host, so it starts without a require.main check.
+require('./mcp').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();
+}