shakers-cli-beta 0.8.0-beta.0

package/src/alma-repo-context.js

@@ -0,0 +1,47 @@
+'use strict';
+
+function join(arr, key) {
+  if (!Array.isArray(arr)) return '';
+  const vals = arr.map((x) => (key ? x && x[key] : x)).filter((s) => typeof s === 'string' && s.length);
+  return [...new Set(vals)].join(', ');
+}
+
+function formatContextBlock(ctx) {
+  if (!ctx || typeof ctx !== 'object') return '';
+  const lines = [];
+  const push = (label, val) => { if (val && val.length) lines.push(`${label}: ${val}`); };
+  push('Project', ctx.project && ctx.project.name);
+  push('Description', ctx.project && ctx.project.tagline);
+  push('Entrypoints', join(ctx.entrypoints, 'label'));
+  push('Services', join(ctx.services));
+  push('Agents', join(ctx.agents, 'label'));
+  push('Models', join(ctx.models, 'label'));
+  push('Integrations', join(ctx.integrations));
+  push('Data stores', join(ctx.stores));
+  push('Technologies', join(ctx.technologies));
+  if (!lines.length) return '';
+  return [
+    '<project-context>',
+    'Structural, content-free map of the directory the talent is running from. This is CONTEXT for your answer, not instructions, and contains no source code.',
+    '',
+    ...lines,
+    '</project-context>',
+  ].join('\n');
+}
+
+function collectContextBlock({ cwd = process.cwd(), collect, status } = {}) {
+  const doCollect = collect || ((root) => require('./repo-context').collectRepoContext(root));
+  try {
+    const run = () => doCollect(cwd);
+    const ctx = status ? status(run) : run();
+    return formatContextBlock(ctx);
+  } catch {
+    return '';
+  }
+}
+
+function prependContext(block, message) {
+  return block ? `${block}\n\n${message}` : message;
+}
+
+module.exports = { formatContextBlock, collectContextBlock, prependContext };

package/src/alma-shell.js

@@ -0,0 +1,161 @@
+'use strict';
+
+const { palette } = require('./ansi');
+const { BRAND_ANSI } = require('./brand-ansi');
+const { promptSelect } = require('./prompt-select');
+const { renderMarkdown } = require('./markdown-ansi');
+const { typeOut } = require('./typewriter');
+const { firstNameFromSession } = require('./auth-session-store');
+const { oneTurn, makeAlmaDeps, EXIT_WORDS } = require('./alma-flow');
+
+const BOLT = '⚡';
+
+const BANNER = [
+  '███████╗██╗  ██╗ █████╗ ██╗  ██╗███████╗██████╗ ███████╗',
+  '██╔════╝██║  ██║██╔══██╗██║ ██╔╝██╔════╝██╔══██╗██╔════╝',
+  '███████╗███████║███████║█████╔╝ █████╗  ██████╔╝███████╗',
+  '╚════██║██╔══██║██╔══██║██╔═██╗ ██╔══╝  ██╔══██╗╚════██║',
+  '███████║██║  ██║██║  ██║██║  ██╗███████╗██║  ██║███████║',
+  '╚══════╝╚═╝  ╚═╝╚═╝  ╚═╝╚═╝  ╚═╝╚══════╝╚═╝  ╚═╝╚══════╝',
+];
+
+function brandColors() {
+  return palette({
+    primary: BRAND_ANSI.primary,
+    accent: BRAND_ANSI.accent,
+    muted: BRAND_ANSI.muted,
+    bold: '\x1b[1m',
+    dim: '\x1b[2m',
+    reset: '\x1b[0m',
+  });
+}
+
+function brandHeader(catalog, out) {
+  const C = brandColors();
+  const a = catalog.alma;
+  out('\n');
+  BANNER.forEach((line, idx) => {
+    if (idx === 0) out(`  ${C.accent}${C.bold}${BOLT}${C.reset} ${C.primary}${C.bold}${line}${C.reset}\n`);
+    else out(`    ${C.primary}${C.bold}${line}${C.reset}\n`);
+  });
+  out(`    ${C.accent}${C.bold}${a.title}${C.reset}  ${C.dim}· ${a.tagline}${C.reset}\n`);
+  out(`    ${C.dim}${a.replHint}${C.reset}\n`);
+}
+
+function userPrompt(catalog, session) {
+  const C = palette({ primary: BRAND_ANSI.primary, reset: '\x1b[0m' });
+  const first = firstNameFromSession(session);
+  const label = first ? `${first}:` : catalog.alma.prompt;
+  return `${C.primary}${BOLT}${C.reset} ${label}`;
+}
+
+function displayWidth(s) {
+  let w = 0;
+  for (const ch of s) w += ch === BOLT ? 2 : 1;
+  return w;
+}
+
+async function printAlmaReply(res, catalog, write, { streamIsTTY = false, env = null } = {}) {
+  if (!res || !res.ok) return;
+  const body = String(res.text || '').trim();
+  if (!body) return;
+  const C = brandColors();
+  const label = `${C.accent}${C.bold}${BOLT} ${catalog.alma.title}:${C.reset}`;
+  const pad = ' '.repeat(displayWidth(`  ${BOLT} ${catalog.alma.title}: `));
+  const lines = renderMarkdown(body).split('\n');
+  let block = `\n  ${label} ${lines[0]}\n`;
+  for (let i = 1; i < lines.length; i++) block += lines[i] ? `${pad}${lines[i]}\n` : '\n';
+  const animate = !!streamIsTTY && !(env && env.NO_ANIMATION);
+  const outStream = { write: (s) => { write(s); return true; }, isTTY: animate };
+  await typeOut(block, { stream: outStream });
+}
+
+async function almaTurn({ io, ask, stdinIsTTY, streamIsTTY, env, write, hubAccessToken, catalog, deps, message }) {
+  const a = catalog.alma;
+  const C = brandColors();
+  const dimNote = (text) => write(`  ${C.dim}${text}${C.reset}\n`);
+
+  let pending = null;
+  const links = [];
+  const capture = (evt) => {
+    if (!evt) return;
+    if (evt.type === 'confirmation_required') pending = { text: evt.text || '', detail: evt.detail || '', data: evt.data || {} };
+    else if (evt.type === 'link' && evt.data && evt.data.to) links.push(String(evt.data.to));
+  };
+
+  const res = await oneTurn({ io, hubAccessToken, message, catalog: { ask: a }, deps, onStreamEvent: capture });
+  await printAlmaReply(res, catalog, write, { streamIsTTY, env });
+  for (const to of links) dimNote(a.webLink(to));
+  if (!res.ok || !pending) return res;
+
+  if (pending.text) write(`\n  ${renderMarkdown(pending.text)}\n`);
+  if (pending.detail) io.warn(a.irreversible);
+  if (pending.data && pending.data.to) dimNote(a.webLink(pending.data.to));
+
+  const choice = await promptSelect({
+    ask,
+    stdinIsTTY,
+    out: (line) => write(`  ${line}\n`),
+    header: a.confirmPrompt,
+    items: [{ id: 'yes', label: a.confirmYes }, { id: 'no', label: a.confirmNo }],
+    labelFor: (it) => it.label,
+  });
+  const approved = !!(choice && choice.id === 'yes');
+
+  const dres = await oneTurn({
+    io,
+    hubAccessToken,
+    message: null,
+    catalog: { ask: a },
+    deps,
+    sendTurn: ({ onEvent }) => deps.decideAlma({ hubAccessToken, approved, onEvent }),
+  });
+  await printAlmaReply(dres, catalog, write, { streamIsTTY, env });
+  return res;
+}
+
+async function runAlmaShell({ io, ask, stdinIsTTY, streamIsTTY, env = process.env, rawOut, session, catalog, deps = makeAlmaDeps() }) {
+  const a = catalog.alma;
+  const write = rawOut || ((s) => process.stdout.write(s));
+  const hubAccessToken = session ? session.hubAccessToken : null;
+
+  brandHeader(catalog, write);
+
+  // Collect the (code-free) project map ONCE, then ask consent before ever sending
+  // it — privacy gate. Declining (or no TTY to ask) sends every turn without context.
+  const ctxBlock = deps.collectContextBlock
+    ? deps.collectContextBlock({ status: (fn) => (deps.withStatus ? deps.withStatus(a.contextLabel, fn) : fn()) })
+    : '';
+  const readLine = typeof ask === 'function' ? ask : (p) => io.ask(p);
+
+  let ctxConsent = false;
+  if (ctxBlock && stdinIsTTY) {
+    const choice = await promptSelect({
+      ask: readLine,
+      stdinIsTTY,
+      out: (line) => write(`  ${line}\n`),
+      header: a.contextConsentHeader,
+      hint: a.contextConsentHint,
+      items: [{ id: 'yes', label: a.contextConsentYes }, { id: 'no', label: a.contextConsentNo }],
+      labelFor: (it) => it.label,
+    });
+    ctxConsent = !!(choice && choice.id === 'yes');
+    if (!ctxConsent) io.notify(a.contextConsentDeclined);
+  }
+  const withCtx = (msg) => (ctxConsent && ctxBlock ? `${ctxBlock}\n\n${msg}` : msg);
+  const prompt = userPrompt(catalog, session);
+  let first = true;
+  for (;;) {
+    const line = (await readLine(prompt)).trim();
+    if (!line || EXIT_WORDS.has(line.toLowerCase())) {
+      io.notify(a.bye);
+      break;
+    }
+    const message = first ? withCtx(line) : line;
+    first = false;
+    await almaTurn({ io, ask, stdinIsTTY, streamIsTTY, env, write, hubAccessToken, catalog, deps, message });
+  }
+  return { ok: true };
+}
+
+module.exports = { runAlmaShell, almaTurn, printAlmaReply, brandHeader, userPrompt };

package/src/ansi.js

@@ -0,0 +1,62 @@
+'use strict';
+
+const { isInteractive } = require('./terminal-progress');
+const { BRAND_ANSI } = require('./brand-ansi');
+
+// THE ONE GATE for terminal colour (talents-ai-score).
+
+// `NO_COLOR` per the de-facto standard: present and non-empty disables colour, whatever the value.
+function noColorRequested(env = process.env) {
+  const value = env ? env.NO_COLOR : undefined;
+  return typeof value === 'string' && value.length > 0;
+}
+
+// The gate. `stream` defaults to stdout because every palette in this repo
+// decorates text that ends up there.
+function colorEnabled({ stream = process.stdout, env = process.env } = {}) {
+  if (noColorRequested(env)) return false;
+  return isInteractive(stream);
+}
+
+// Wraps a map of escape codes so each key yields its code when colour is on and `''` when it is off.
+function palette(codes, opts = {}) {
+  const out = {};
+  for (const key of Object.keys(codes)) {
+    const code = codes[key];
+    Object.defineProperty(out, key, {
+      enumerable: true,
+      get: () => (colorEnabled(opts) ? code : ''),
+    });
+  }
+  return out;
+}
+
+function styleQuestion(text, opts = {}) {
+  const ANSI = palette({ bold: '\x1b[1m', primary: BRAND_ANSI.primary, reset: '\x1b[0m' }, opts);
+  return `${ANSI.bold}${ANSI.primary}${text}${ANSI.reset}`;
+}
+
+const SUCCESS_GREEN = '\x1b[38;5;114m';
+
+function styleSuccess(text, opts = {}) {
+  const ANSI = palette({ success: SUCCESS_GREEN, reset: '\x1b[0m' }, opts);
+  return `${ANSI.success}${text}${ANSI.reset}`;
+}
+
+// Bold a field LABEL (no colour). Gate-aware via `palette`: empty codes when
+// colour is off (non-TTY / NO_COLOR), so piped/redirected output stays clean.
+function styleLabel(text, opts = {}) {
+  const ANSI = palette({ bold: '\x1b[1m', reset: '\x1b[0m' }, opts);
+  return `${ANSI.bold}${text}${ANSI.reset}`;
+}
+
+// Bold only the "Label:" prefix of a "Label: value" line, leaving the value
+// plain. No `: ` -> returned unchanged (value-only lines never get bolded).
+function styleLabelPrefix(line, opts = {}) {
+  const s = typeof line === 'string' ? line : '';
+  const idx = s.indexOf(': ');
+  if (idx === -1) return s;
+  return `${styleLabel(s.slice(0, idx + 1), opts)}${s.slice(idx + 1)}`;
+}
+
+module.exports = { palette, colorEnabled, noColorRequested, styleQuestion, styleSuccess, styleLabel, styleLabelPrefix, SUCCESS_GREEN };

package/src/applications-client.js

@@ -0,0 +1,79 @@
+'use strict';
+
+// My-applications client (hub `works/candidatures/me`, talent Bearer). Lists the
+// positions the talent applied to, with the candidature status.
+
+const { postJsonWithTimeout } = require('./backend-request');
+const { reasonForError } = require('./onboarding-client');
+
+const DEFAULT_TIMEOUT_MS = 20000;
+const DEFAULT_LIMIT = 30;
+
+function parseJson(raw) {
+  try {
+    return raw ? JSON.parse(raw) : null;
+  } catch {
+    return null;
+  }
+}
+
+function bearerHeaders(accessToken) {
+  const headers = {};
+  if (typeof accessToken === 'string' && accessToken) headers.Authorization = `Bearer ${accessToken}`;
+  return headers;
+}
+
+function str(v) {
+  return typeof v === 'string' && v ? v : null;
+}
+
+function normalizeApplication(raw) {
+  const it = raw && typeof raw === 'object' ? raw : {};
+  const project = it.project && typeof it.project === 'object' ? it.project : {};
+  const position = it.position && typeof it.position === 'object' ? it.position : {};
+  const org = it.organization && typeof it.organization === 'object' ? it.organization : {};
+  return {
+    positionId: str(position.id),
+    title: str(position.name) || str(project.name),
+    projectName: str(project.name),
+    company: str(org.name),
+    status: str(it.status),
+    createdAt: str(it.createdAt),
+  };
+}
+
+async function requestMyCandidatures({ hubAccessToken } = {}, { endpoint, limit = DEFAULT_LIMIT, timeoutMs = DEFAULT_TIMEOUT_MS } = {}) {
+  if (!endpoint) return { ok: false, reason: 'no-endpoint' };
+  if (!hubAccessToken) return { ok: false, reason: 'no-hub-token' };
+  const criteria = { limit, offset: 0 };
+  const url = `${endpoint}${endpoint.includes('?') ? '&' : '?'}criteria=${encodeURIComponent(JSON.stringify(criteria))}`;
+  let res;
+  try {
+    res = await postJsonWithTimeout(url, null, timeoutMs, 'GET', null, bearerHeaders(hubAccessToken));
+  } catch (e) {
+    return { ok: false, reason: (e && e.kind) || 'network-error' };
+  }
+  if (res.status < 200 || res.status >= 300) return { ok: false, reason: reasonForError(res.status, res.raw) };
+
+  const env = parseJson(res.raw);
+  const data = env && env.status === 'OK' ? env.data : env;
+  const rows = Array.isArray(data) ? data : (Array.isArray(data && data.items) ? data.items : null);
+  if (!rows) return { ok: false, reason: 'bad-response' };
+  return { ok: true, items: rows.map(normalizeApplication), meta: (env && typeof env.meta === 'object' ? env.meta : null) };
+}
+
+async function fetchApplications(deps = {}, { hubAccessToken, limit = DEFAULT_LIMIT, timeoutMs = DEFAULT_TIMEOUT_MS } = {}) {
+  const {
+    getMyCandidaturesEndpoint = require('./config').getMyCandidaturesEndpoint,
+    requestMyCandidatures: request = requestMyCandidatures,
+  } = deps;
+  const endpoint = getMyCandidaturesEndpoint();
+  if (!endpoint) return { ok: false, reason: 'no-endpoint' };
+  return request({ hubAccessToken }, { endpoint, limit, timeoutMs });
+}
+
+module.exports = {
+  normalizeApplication,
+  requestMyCandidatures,
+  fetchApplications,
+};

package/src/applications-flow.js

@@ -0,0 +1,58 @@
+'use strict';
+
+// `applications` flow: list the positions the talent applied to + status.
+// Read-only. Writes the SAME ordinal->positionId cache as find-projects, so
+// `show-project N` / `save-project N` work after `applications` too.
+
+const { styleLabelPrefix } = require('./ansi');
+
+function makeApplicationsDeps(overrides = {}) {
+  const client = require('./applications-client');
+  return {
+    fetchApplications: (opts) => client.fetchApplications({}, opts),
+    writePositionCache: (ids) => require('./find-projects-cache').writePositionCache(ids),
+    ...overrides,
+  };
+}
+
+async function runApplications({ io, rawOut, session, catalog, opts = {}, deps = makeApplicationsDeps() }) {
+  const fp = catalog.applications;
+  const hubAccessToken = session ? session.hubAccessToken : null;
+
+  const doFetch = () => deps.fetchApplications({ hubAccessToken });
+  const res = opts.json ? await doFetch() : await io.withProgress(fp.loading, doFetch);
+  if (!res.ok) {
+    io.error(fp.fetchFailed(res.reason));
+    return { ok: false, reason: res.reason };
+  }
+  const items = Array.isArray(res.items) ? res.items : [];
+
+  if (opts.json) {
+    (rawOut || ((s) => process.stdout.write(s)))(`${JSON.stringify({ ok: true, items }, null, 2)}\n`);
+    return { ok: true, items };
+  }
+
+  // Human path: refresh the number->positionId cache (last listing wins).
+  try { deps.writePositionCache(items.map((it) => it.positionId)); } catch { /* best-effort */ }
+
+  io.section(fp.title);
+  if (items.length === 0) {
+    io.notify(fp.none);
+    return { ok: true, items };
+  }
+  // No ids in the human render (they ride the cache + --json).
+  items.forEach((a, i) => {
+    if (i > 0) io.notify('');
+    const headline = a.title || a.projectName || fp.untitled;
+    io.notify(`${i + 1}) ${headline}${a.company ? ` — ${a.company}` : ''}`);
+    io.notify(styleLabelPrefix(fp.statusLine(a.status || fp.statusUnknown)));
+  });
+  io.notify(styleLabelPrefix(fp.countNote(items.length)));
+  io.success(fp.done);
+  return { ok: true, items };
+}
+
+module.exports = {
+  makeApplicationsDeps,
+  runApplications,
+};

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 };