shakers-cli 0.0.0-stage → 0.14.1

package/src/auth-client.js

@@ -0,0 +1,144 @@
+'use strict';
+
+const { postJsonWithTimeout, extractSetCookie } = require('./backend-request');
+
+// Login / token acquisition against the Hub's better-auth email engine (owner decision, supersedes ADR-031 for the email path).
+
+const DEFAULT_TIMEOUT_MS = 20000;
+const SESSION_COOKIE_NAME = 'better-auth.session_token';
+// Refresh the cookie session's own validity from the Set-Cookie Max-Age; fall
+// back to 7 days (better-auth's default) when the attribute is absent.
+const DEFAULT_COOKIE_TTL_SECONDS = 7 * 24 * 60 * 60;
+
+function parseJson(raw) {
+  try { return raw ? JSON.parse(raw) : null; } catch { return null; }
+}
+
+// `exp` (JWT seconds) -> ISO, or null. Never throws.
+function expiresAtFromJwt(token) {
+  try {
+    const parts = String(token).split('.');
+    if (parts.length < 2) return null;
+    const payload = JSON.parse(Buffer.from(parts[1], 'base64url').toString('utf8'));
+    const exp = typeof payload.exp === 'number' && Number.isFinite(payload.exp) ? payload.exp : null;
+    return exp === null ? null : new Date(exp * 1000).toISOString();
+  } catch {
+    return null;
+  }
+}
+
+// ISO expiry for the session cookie, read from the Set-Cookie `Max-Age` (or
+// `Expires`) of the named cookie; defaults to +7 days when neither is present.
+function cookieExpiresAtFromHeaders(headers, name = SESSION_COOKIE_NAME) {
+  const raw = headers && headers['set-cookie'];
+  const list = Array.isArray(raw) ? raw : (typeof raw === 'string' && raw ? [raw] : []);
+  // Match the base name with or without better-auth's HTTPS `__Secure-`/`__Host-` prefixes.
+  const names = [name, `__Secure-${name}`, `__Host-${name}`];
+  const entry = list.find((e) => typeof e === 'string' && names.some((n) => e.startsWith(`${n}=`)));
+  if (entry) {
+    const maxAge = /(?:^|;\s*)max-age=(\d+)/i.exec(entry);
+    if (maxAge) return new Date(Date.now() + Number(maxAge[1]) * 1000).toISOString();
+    const expires = /(?:^|;\s*)expires=([^;]+)/i.exec(entry);
+    if (expires) {
+      const t = Date.parse(expires[1]);
+      if (Number.isFinite(t)) return new Date(t).toISOString();
+    }
+  }
+  return new Date(Date.now() + DEFAULT_COOKIE_TTL_SECONDS * 1000).toISOString();
+}
+
+function normalizeResponse(status, raw) {
+  if (status >= 200 && status < 300) {
+    let json = null;
+    try { json = raw ? JSON.parse(raw) : null; } catch { json = null; }
+    const payload = json && typeof json.data === 'object' && json.data !== null ? json.data : json;
+    const accessToken = payload && typeof payload.accessToken === 'string' && payload.accessToken ? payload.accessToken : null;
+    if (!accessToken) return { ok: false, reason: 'bad-response', status };
+    const expiresAt = payload && typeof payload.expiresAt === 'string' && payload.expiresAt ? payload.expiresAt : null;
+    const emailRaw = payload && (payload.userEmail || payload.email);
+    const email = typeof emailRaw === 'string' && emailRaw ? emailRaw : null;
+    const hubAccessToken = payload && typeof payload.hubAccessToken === 'string' && payload.hubAccessToken ? payload.hubAccessToken : null;
+    return { ok: true, accessToken, expiresAt, email, hubAccessToken };
+  }
+  if (status === 401) return { ok: false, reason: 'invalid-credentials', status };
+  if (status === 409 || status === 422) return { ok: false, reason: 'no-email-password', status };
+  if (status === 502 || status === 503) return { ok: false, reason: 'upstream', status };
+  return { ok: false, reason: 'http-error', status };
+}
+
+// Maps the sign-in POST outcome to a captured cookie + email, or a named reason.
+function normalizeSignIn(status, raw, headers) {
+  if (status >= 200 && status < 300) {
+    const cookie = extractSetCookie(headers, SESSION_COOKIE_NAME);
+    if (!cookie) return { ok: false, reason: 'bad-response', status };
+    const body = parseJson(raw);
+    const user = body && typeof body === 'object' ? body.user : null;
+    const emailRaw = user && typeof user.email === 'string' ? user.email : null;
+    return {
+      ok: true,
+      cookie,
+      cookieExpiresAt: cookieExpiresAtFromHeaders(headers),
+      email: emailRaw || null,
+    };
+  }
+  if (status === 401) return { ok: false, reason: 'invalid-credentials', status };
+  if (status === 409 || status === 422) return { ok: false, reason: 'no-email-password', status };
+  if (status === 502 || status === 503) return { ok: false, reason: 'upstream', status };
+  return { ok: false, reason: 'http-error', status };
+}
+
+// Mints a hub JWT from a better-auth session cookie: `GET {tokenEndpoint}` with the `Cookie` header.
+async function requestAuthToken({ cookie } = {}, { endpoint, timeoutMs = DEFAULT_TIMEOUT_MS } = {}) {
+  if (!endpoint) return { ok: false, reason: 'no-endpoint' };
+  if (!cookie) return { ok: false, reason: 'no-cookie' };
+  let res;
+  try {
+    res = await postJsonWithTimeout(endpoint, null, timeoutMs, 'GET', null, { Cookie: cookie });
+  } catch (e) {
+    return { ok: false, reason: (e && e.kind) || 'network-error' };
+  }
+  if (res.status < 200 || res.status >= 300) return { ok: false, reason: 'http-error', status: res.status };
+  const body = parseJson(res.raw);
+  const token = body && typeof body.token === 'string' && body.token ? body.token : null;
+  if (!token) return { ok: false, reason: 'bad-response', status: res.status };
+  return { ok: true, accessToken: token, expiresAt: expiresAtFromJwt(token) };
+}
+
+// The full email login: sign-in (capture cookie) -> mint JWT.
+async function requestLogin(
+  { email, password },
+  { signInEndpoint, tokenEndpoint, timeoutMs = DEFAULT_TIMEOUT_MS } = {},
+) {
+  if (!signInEndpoint) return { ok: false, reason: 'no-endpoint' };
+  let signIn;
+  try {
+    const { status, raw, headers } = await postJsonWithTimeout(signInEndpoint, { email, password }, timeoutMs);
+    signIn = normalizeSignIn(status, raw, headers);
+  } catch (e) {
+    return { ok: false, reason: (e && e.kind) || 'local-error' };
+  }
+  if (!signIn.ok) return signIn;
+
+  const tok = await requestAuthToken({ cookie: signIn.cookie }, { endpoint: tokenEndpoint, timeoutMs });
+  if (!tok.ok) return { ok: false, reason: 'token-fetch-failed', status: tok.status || null };
+
+  return {
+    ok: true,
+    accessToken: tok.accessToken,
+    hubAccessToken: tok.accessToken,
+    expiresAt: tok.expiresAt,
+    email: signIn.email || (typeof email === 'string' ? email : null),
+    cookie: signIn.cookie,
+    cookieExpiresAt: signIn.cookieExpiresAt,
+  };
+}
+
+module.exports = {
+  requestLogin,
+  requestAuthToken,
+  normalizeSignIn,
+  normalizeResponse,
+  expiresAtFromJwt,
+  SESSION_COOKIE_NAME,
+  DEFAULT_TIMEOUT_MS,
+};

package/src/auth-device-client.js

@@ -0,0 +1,118 @@
+'use strict';
+
+const { postJsonWithTimeout } = require('./backend-request');
+
+// OAuth 2.0 Device Authorization Grant (RFC 8628) client against the Hub broker.
+
+const DEFAULT_TIMEOUT_MS = 20000;
+
+const CLIENT_ID = 'shakers-cli';
+const DEVICE_GRANT_TYPE = 'urn:ietf:params:oauth:grant-type:device_code';
+
+function parseJson(raw) {
+  try {
+    return raw ? JSON.parse(raw) : null;
+  } catch {
+    return null;
+  }
+}
+
+function unwrap(json) {
+  if (json && typeof json === 'object' && json.data && typeof json.data === 'object') return json.data;
+  return json && typeof json === 'object' ? json : null;
+}
+
+function str(value) {
+  return typeof value === 'string' && value ? value : null;
+}
+
+function posInt(value) {
+  return typeof value === 'number' && Number.isFinite(value) && value > 0 ? Math.floor(value) : null;
+}
+
+async function requestDeviceAuthorization({ endpoint, clientId = CLIENT_ID, scope = null, timeoutMs = DEFAULT_TIMEOUT_MS } = {}) {
+  if (!endpoint) return { ok: false, reason: 'no-endpoint' };
+  const body = { client_id: clientId };
+  if (scope) body.scope = scope;
+  let res;
+  try {
+    res = await postJsonWithTimeout(endpoint, body, timeoutMs);
+  } catch (e) {
+    return { ok: false, reason: (e && e.kind) || 'network-error' };
+  }
+  const { status, raw } = res;
+  if (status === 502 || status === 503) return { ok: false, reason: 'upstream', status };
+  if (status < 200 || status >= 300) return { ok: false, reason: 'http-error', status };
+
+  const data = unwrap(parseJson(raw));
+  const deviceCode = data && str(data.device_code);
+  const userCode = data && str(data.user_code);
+  const verificationUri = data && str(data.verification_uri);
+  if (!deviceCode || !userCode || !verificationUri) return { ok: false, reason: 'bad-response', status };
+
+  return {
+    ok: true,
+    deviceCode,
+    userCode,
+    verificationUri,
+    verificationUriComplete: (data && str(data.verification_uri_complete)) || verificationUri,
+    expiresIn: (data && posInt(data.expires_in)) || 600,
+    interval: (data && posInt(data.interval)) || 5,
+  };
+}
+
+// One poll. Success carries the better-auth SESSION token (access_token), NOT the API JWT.
+async function requestDeviceToken({ deviceCode, clientId = CLIENT_ID }, { endpoint, timeoutMs = DEFAULT_TIMEOUT_MS } = {}) {
+  if (!endpoint) return { status: 'error', reason: 'no-endpoint' };
+  if (!deviceCode) return { status: 'error', reason: 'no-device-code' };
+  const body = { grant_type: DEVICE_GRANT_TYPE, device_code: deviceCode, client_id: clientId };
+  let res;
+  try {
+    res = await postJsonWithTimeout(endpoint, body, timeoutMs);
+  } catch (e) {
+    return { status: 'error', reason: (e && e.kind) || 'network-error' };
+  }
+  const { status, raw } = res;
+  const data = unwrap(parseJson(raw));
+
+  if (status >= 200 && status < 300) {
+    const accessToken = data && (str(data.access_token) || str(data.accessToken) || str(data.token));
+    if (!accessToken) return { status: 'error', reason: 'bad-response', http: status };
+    return {
+      status: 'authorized',
+      accessToken,
+      tokenType: (data && str(data.token_type)) || 'Bearer',
+      expiresIn: data && posInt(data.expires_in),
+      isNewUser: !!(data && (data.isNewUser === true || data.is_new_user === true)),
+      email: data && (str(data.email) || str(data.userEmail)),
+    };
+  }
+
+  const code = data && (str(data.error) || str(data.code));
+  if (code === 'authorization_pending') return { status: 'pending' };
+  if (code === 'slow_down') return { status: 'slow_down' };
+  if (code === 'access_denied') return { status: 'denied' };
+  if (code === 'expired_token') return { status: 'expired' };
+  if (status === 502 || status === 503) return { status: 'error', reason: 'upstream', http: status };
+  return { status: 'error', reason: code || 'http-error', http: status };
+}
+
+async function requestApiToken({ accessToken }, { endpoint, timeoutMs = DEFAULT_TIMEOUT_MS } = {}) {
+  if (!endpoint) return { ok: false, reason: 'no-endpoint' };
+  if (!accessToken) return { ok: false, reason: 'no-access-token' };
+  let res;
+  try {
+    res = await postJsonWithTimeout(endpoint, null, timeoutMs, 'GET', null, { Authorization: `Bearer ${accessToken}` });
+  } catch (e) {
+    return { ok: false, reason: (e && e.kind) || 'network-error' };
+  }
+  const { status, raw } = res;
+  if (status === 502 || status === 503) return { ok: false, reason: 'upstream', status };
+  if (status < 200 || status >= 300) return { ok: false, reason: 'http-error', status };
+  const data = unwrap(parseJson(raw));
+  const token = data && str(data.token);
+  if (!token) return { ok: false, reason: 'bad-response', status };
+  return { ok: true, token };
+}
+
+module.exports = { requestDeviceAuthorization, requestDeviceToken, requestApiToken, CLIENT_ID, DEVICE_GRANT_TYPE, DEFAULT_TIMEOUT_MS };

package/src/auth-method-picker.js

@@ -0,0 +1,44 @@
+'use strict';
+
+const { runInteractiveMultiSelect } = require('./interactive-select');
+const { methodsForFlow, methodLabel } = require('./auth-methods');
+
+// The shared interactive method picker for the CLI (talents-ai-score).
+async function askNumberedChoice(ask, promptText, count) {
+  const raw = (await ask(promptText)).trim();
+  if (!raw) return null;
+  const n = Number.parseInt(raw, 10);
+  if (!Number.isInteger(n) || n < 1 || n > count) return null;
+  return n - 1;
+}
+
+async function chooseAuthMethod({ flow, ask, stdinIsTTY, catalog, input, output } = {}) {
+  const methods = methodsForFlow(flow);
+  if (methods.length === 0) return null;
+  if (methods.length === 1) return methods[0].id;
+  if (!stdinIsTTY) return methods[0].id;
+
+  if (ask && typeof ask.suspend === 'function') {
+    ask.suspend();
+    const picked = await runInteractiveMultiSelect({
+      items: methods,
+      labelFor: (m) => methodLabel(m, catalog),
+      header: catalog.chooseMethodHeading,
+      hint: catalog.selectHint,
+      single: true,
+      ...(input ? { input } : {}),
+      ...(output ? { output } : {}),
+    });
+    if (typeof ask.resume === 'function') ask.resume();
+    if (!picked || picked.length === 0) return null;
+    return picked[0].id;
+  }
+
+  const stream = output || process.stdout;
+  stream.write(`\n  ${catalog.chooseMethodHeading}\n`);
+  methods.forEach((m, i) => stream.write(`    ${i + 1}) ${methodLabel(m, catalog)}\n`));
+  const idx = await askNumberedChoice(ask, `  ${catalog.chooseMethodPrompt(methods.length)}`, methods.length);
+  return idx === null ? null : methods[idx].id;
+}
+
+module.exports = { chooseAuthMethod, askNumberedChoice };

package/src/auth-methods.js

@@ -0,0 +1,35 @@
+'use strict';
+
+// The SINGLE source of truth for which auth methods exist and where each one is offered (talents-ai-score).
+const AUTH_METHODS = [
+  { id: 'email', labelKey: 'methodEmail', availableFor: { login: true, register: true } },
+  { id: 'google', labelKey: 'methodGoogle', availableFor: { login: true, register: true } },
+  { id: 'linkedin', labelKey: 'methodLinkedin', availableFor: { login: true, register: true } },
+];
+
+// Social methods share ONE device flow; only the `provider` query param differs.
+const SOCIAL_METHODS = new Set(['google', 'linkedin']);
+function isSocialMethod(id) {
+  return SOCIAL_METHODS.has(id);
+}
+
+function methodsForFlow(flow) {
+  return AUTH_METHODS.filter((m) => m.availableFor && m.availableFor[flow] === true);
+}
+
+function methodIdsForFlow(flow) {
+  return methodsForFlow(flow).map((m) => m.id);
+}
+
+function isMethodAvailable(id, flow) {
+  return methodIdsForFlow(flow).includes(id);
+}
+
+function methodLabel(method, catalog) {
+  const entry = typeof method === 'string' ? AUTH_METHODS.find((m) => m.id === method) : method;
+  const key = entry && entry.labelKey;
+  if (catalog && key && catalog[key]) return catalog[key];
+  return entry ? entry.id : String(method);
+}
+
+module.exports = { AUTH_METHODS, SOCIAL_METHODS, isSocialMethod, methodsForFlow, methodIdsForFlow, isMethodAvailable, methodLabel };

package/src/auth-session-store.js

@@ -0,0 +1,215 @@
+'use strict';
+
+const crypto = require('crypto');
+const fs = require('fs');
+const path = require('path');
+const { getConfigDir } = require('./config-dir');
+
+// `~/.config/shakers/auth-session.json` — the logged-in Talent's session (talents-ai-score, issue 122 / ADR-044).
+
+// Hub's `UserSubtypeEnum` (shared/domain/enum/user-subtype.enum.ts), copied VERBATIM — this repo never invents a value the wire does not send.
+const PLATFORM_TALENT_USER_TYPES = new Set(['WORKS_TALENT', 'WORKS_PARTNER']);
+const KNOWN_USER_TYPES = new Set(['HUB', 'WORKS_CLIENT', 'WORKS_TALENT', 'WORKS_PARTNER']);
+
+// Decodes (NEVER verifies — this module has no secret to verify with, and the claim only ever picks which COPY prints) a JWT's payload segment.
+function decodeJwtPayload(token) {
+  if (typeof token !== 'string' || !token) return null;
+  const parts = token.split('.');
+  if (parts.length !== 3) return null;
+  try {
+    const json = Buffer.from(parts[1], 'base64url').toString('utf8');
+    const parsed = JSON.parse(json);
+    return parsed && typeof parsed === 'object' && !Array.isArray(parsed) ? parsed : null;
+  } catch {
+    return null;
+  }
+}
+
+// The one place `hubAccessToken` -> `userType` happens.
+function userTypeFromHubToken(hubAccessToken) {
+  const payload = decodeJwtPayload(hubAccessToken);
+  const userType = payload && typeof payload.userType === 'string' ? payload.userType : null;
+  return userType && KNOWN_USER_TYPES.has(userType) ? userType : null;
+}
+
+function emailFromHubToken(hubAccessToken) {
+  const payload = decodeJwtPayload(hubAccessToken);
+  const email = payload && typeof payload.email === 'string' ? payload.email : null;
+  return email || null;
+}
+
+function firstNameFromSession(session) {
+  if (!session || typeof session !== 'object') return null;
+  const token = (typeof session.hubAccessToken === 'string' && session.hubAccessToken)
+    ? session.hubAccessToken
+    : (typeof session.accessToken === 'string' ? session.accessToken : null);
+  const payload = decodeJwtPayload(token);
+  if (!payload) return null;
+  const raw = [payload.name, payload.given_name, payload.firstName, payload.first_name]
+    .find((v) => typeof v === 'string' && v.trim());
+  if (!raw) return null;
+  const first = raw.trim().split(/\s+/)[0];
+  return first || null;
+}
+
+// `exp` (JWT seconds-since-epoch) -> ISO string, or null.
+function expiresAtFromToken(token) {
+  const payload = decodeJwtPayload(token);
+  const exp = payload && typeof payload.exp === 'number' && Number.isFinite(payload.exp) ? payload.exp : null;
+  if (exp === null) return null;
+  try {
+    return new Date(exp * 1000).toISOString();
+  } catch {
+    return null;
+  }
+}
+
+// The ONE predicate every gate reads (src/report-gating.js), so two call
+// sites can never disagree about which `userType` values count as a Talent.
+function isPlatformTalent(session) {
+  return !!(session && PLATFORM_TALENT_USER_TYPES.has(session.userType));
+}
+
+const SESSION_FILE_NAME = 'auth-session.json';
+
+// Bumped when the shape changes in a way an older/newer CLI cannot read.
+const SESSION_FILE_VERSION = 2;
+
+function configDir(env = process.env) {
+  return getConfigDir(env);
+}
+
+function authSessionPath(env = process.env) {
+  return path.join(configDir(env), SESSION_FILE_NAME);
+}
+
+// ATOMIC 0600 write.
+function saveAuthSession(session, env = process.env, { fs: fsImpl = fs } = {}) {
+  const explicitHubToken = typeof session.hubAccessToken === 'string' && session.hubAccessToken ? session.hubAccessToken : null;
+  const hubAccessToken = explicitHubToken || (typeof session.accessToken === 'string' && session.accessToken ? session.accessToken : null);
+
+  const cookie = typeof session.cookie === 'string' && session.cookie ? session.cookie : null;
+  let expiresAt;
+  let accessTokenExpiresAt;
+  if (cookie) {
+    expiresAt = (typeof session.cookieExpiresAt === 'string' && session.cookieExpiresAt)
+      ? session.cookieExpiresAt
+      : (typeof session.expiresAt === 'string' && session.expiresAt ? session.expiresAt : null);
+    accessTokenExpiresAt = (typeof session.accessTokenExpiresAt === 'string' && session.accessTokenExpiresAt)
+      ? session.accessTokenExpiresAt
+      : expiresAtFromToken(session.accessToken);
+  } else {
+    expiresAt = (typeof session.expiresAt === 'string' && session.expiresAt) ? session.expiresAt : expiresAtFromToken(session.accessToken);
+    accessTokenExpiresAt = expiresAt;
+  }
+
+  const payload = `${JSON.stringify(
+    {
+      accessToken: typeof session.accessToken === 'string' && session.accessToken ? session.accessToken : null,
+      expiresAt: expiresAt ?? null,
+      accessTokenExpiresAt: accessTokenExpiresAt ?? null,
+      cookie,
+      email: (typeof session.email === 'string' && session.email ? session.email : null)
+        || emailFromHubToken(hubAccessToken),
+      hubAccessToken,
+      // Decoded once from the SAME `hubAccessToken` this session carries (see the
+      // module docblock) — never a second round-trip or source of truth.
+      userType: userTypeFromHubToken(hubAccessToken),
+      version: SESSION_FILE_VERSION,
+    },
+    null,
+    2,
+  )}\n`;
+
+  const target = authSessionPath(env);
+  const dir = path.dirname(target);
+  fsImpl.mkdirSync(dir, { recursive: true, mode: 0o700 });
+
+  const tmp = path.join(dir, `.${SESSION_FILE_NAME}.${process.pid}.${crypto.randomBytes(6).toString('hex')}.tmp`);
+  let fd = null;
+  try {
+    fd = fsImpl.openSync(tmp, 'wx', 0o600);
+    fsImpl.writeFileSync(fd, payload);
+    try { fsImpl.fsyncSync(fd); } catch { /* e.g. EINVAL on some filesystems */ }
+    fsImpl.closeSync(fd);
+    fd = null;
+    fsImpl.renameSync(tmp, target);
+  } catch (e) {
+    if (fd !== null) { try { fsImpl.closeSync(fd); } catch { /* already closed */ } }
+    // A stale temp would accumulate one bearer-token-holding file per failure.
+    try { fsImpl.unlinkSync(tmp); } catch { /* never existed */ }
+    throw e;
+  }
+  return target;
+}
+
+// Reads the file, or `null` for "no session": missing, unreadable, malformed JSON, unrecognized `version`, or missing the one field without which there is no session (`accessToken`).
+function loadAuthSession(env = process.env, { fs: fsImpl = fs } = {}) {
+  let parsed;
+  try {
+    parsed = JSON.parse(fsImpl.readFileSync(authSessionPath(env), 'utf8'));
+  } catch {
+    return null;
+  }
+  if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) return null;
+  if (parsed.version !== SESSION_FILE_VERSION) return null;
+  // A usable session needs at least ONE credential: the durable cookie (email/
+  // better-auth) or a JWT (Google/legacy, or an email session whose JWT is cached).
+  const hasCookie = typeof parsed.cookie === 'string' && parsed.cookie;
+  const hasToken = typeof parsed.accessToken === 'string' && parsed.accessToken;
+  if (!hasCookie && !hasToken) return null;
+  const hubAccessToken = typeof parsed.hubAccessToken === 'string' && parsed.hubAccessToken ? parsed.hubAccessToken : null;
+  const email = (typeof parsed.email === 'string' && parsed.email ? parsed.email : null) || emailFromHubToken(hubAccessToken);
+  return {
+    accessToken: hasToken ? parsed.accessToken : null,
+    expiresAt: typeof parsed.expiresAt === 'string' ? parsed.expiresAt : null,
+    accessTokenExpiresAt: typeof parsed.accessTokenExpiresAt === 'string' ? parsed.accessTokenExpiresAt : null,
+    cookie: hasCookie ? parsed.cookie : null,
+    email,
+    hubAccessToken,
+    userType: typeof parsed.userType === 'string' && KNOWN_USER_TYPES.has(parsed.userType) ? parsed.userType : null,
+  };
+}
+
+// Removes the file. Idempotent and never throws — `logout` on no session is a
+// no-op, not a failure.
+function clearAuthSession(env = process.env, { fs: fsImpl = fs } = {}) {
+  try {
+    fsImpl.unlinkSync(authSessionPath(env));
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+// `none | active | expired`, the three states the caller needs to give the Talent a true message.
+function sessionStatus(session, now = Date.now()) {
+  // A credential is either the durable cookie (email) or a JWT (Google/legacy).
+  const hasCred = !!(session && ((typeof session.accessToken === 'string' && session.accessToken) || (typeof session.cookie === 'string' && session.cookie)));
+  if (!hasCred) return 'none';
+  const expiry = Date.parse(String(session.expiresAt || ''));
+  if (!Number.isFinite(expiry)) return 'expired';
+  return expiry > now ? 'active' : 'expired';
+}
+
+// The single predicate the rest of the CLI asks: is there a usable session right
+// now? Everything gating reads reduces to this.
+function isLoggedIn(env = process.env, now = Date.now(), deps = {}) {
+  return sessionStatus(loadAuthSession(env, deps), now) === 'active';
+}
+
+module.exports = {
+  SESSION_FILE_NAME,
+  SESSION_FILE_VERSION,
+  authSessionPath,
+  saveAuthSession,
+  loadAuthSession,
+  clearAuthSession,
+  sessionStatus,
+  isLoggedIn,
+  isPlatformTalent,
+  PLATFORM_TALENT_USER_TYPES,
+  decodeJwtPayload,
+  emailFromHubToken,
+  firstNameFromSession,
+};

package/src/authorship-mismatch.js

@@ -0,0 +1,62 @@
+'use strict';
+
+// Display-only authorship-transparency check (talents-ai-score).
+//
+// Warns the talent when their commits in the selected repos are authored under
+// an email that is not their Shakers account email, so their own work would be
+// attributed to nobody. This is a WARNING surface ONLY: it reads each repo's
+// CONFIGURED commit identity (`git config user.email`) and compares counts the
+// attribution path already produced — it NEVER feeds attribution/scoring.
+// git-activity.js owns `authoredCommitCount`; nothing here changes any count.
+
+const { execFileSync } = require('child_process');
+
+// The repo's locally configured commit identity. A plain config read, NOT the
+// authorship log parse — it only names who new commits here would be attributed to.
+function readConfiguredEmail(root) {
+  try {
+    const out = execFileSync('git', ['-C', root, 'config', '--get', 'user.email'], {
+      encoding: 'utf8',
+      timeout: 5000,
+      stdio: ['ignore', 'pipe', 'ignore'],
+    });
+    const value = String(out || '').trim();
+    return value || null;
+  } catch {
+    return null;
+  }
+}
+
+function normalize(email) {
+  return String(email || '').trim().toLowerCase();
+}
+
+// Returns { accountEmail, emails: [configured emails that differ from the account] }
+// when the talent's own commits are plausibly going unattributed, else null.
+//
+// Conservative on purpose (a false warning erodes trust more than a missed one):
+// it fires only when the account email is known, the selection HAS commits, NONE
+// are attributed to the account, and at least one repo is configured under a
+// different email we can name.
+function detectAuthorshipMismatch(toplevels, accountEmail, gitActivity, { readEmail = readConfiguredEmail } = {}) {
+  const account = normalize(accountEmail);
+  if (!account) return null;
+  if (!gitActivity) return null;
+  const commits = gitActivity.commitCount || 0;
+  const authored = gitActivity.authoredCommitCount || 0;
+  if (commits === 0 || authored > 0) return null;
+
+  const emails = [];
+  const seen = new Set();
+  for (const root of Array.isArray(toplevels) ? toplevels : []) {
+    const configured = readEmail(root);
+    const key = normalize(configured);
+    if (!key || key === account || seen.has(key)) continue;
+    seen.add(key);
+    emails.push(String(configured).trim());
+  }
+  if (emails.length === 0) return null;
+  return { accountEmail: String(accountEmail).trim(), emails };
+}
+
+module.exports = { detectAuthorshipMismatch, readConfiguredEmail };