shakers-cli-beta 0.8.0-beta.0

package/src/detectors.js

@@ -0,0 +1,221 @@
+'use strict';
+
+// Catalog of AI tools for developers.
+
+const CATEGORIES = {
+  AGENTIC_CLI: 'CLI agéntica',
+  AI_EDITOR: 'Editor con IA',
+  IDE_ASSISTANT: 'Asistente en IDE',
+  COMPLETION: 'Autocompletado',
+  AI_TERMINAL: 'Terminal con IA',
+};
+
+const detectors = [
+  {
+    id: 'claude-code',
+    name: 'Claude Code',
+    vendor: 'Anthropic',
+    category: CATEGORIES.AGENTIC_CLI,
+    signals: [
+      { type: 'projectPath', path: '.claude' },
+      { type: 'projectPath', path: 'CLAUDE.md' },
+      { type: 'projectPath', path: '.mcp.json' },
+      { type: 'homePath', path: '.claude' },
+      { type: 'bin', name: 'claude' },
+    ],
+  },
+  {
+    id: 'cursor',
+    name: 'Cursor',
+    vendor: 'Anysphere',
+    category: CATEGORIES.AI_EDITOR,
+    signals: [
+      { type: 'projectPath', path: '.cursor' },
+      { type: 'projectPath', path: '.cursorrules' },
+      { type: 'homePath', path: '.cursor' },
+      { type: 'bin', name: 'cursor' },
+    ],
+  },
+  {
+    id: 'github-copilot',
+    name: 'GitHub Copilot',
+    vendor: 'GitHub',
+    category: CATEGORIES.IDE_ASSISTANT,
+    signals: [
+      { type: 'projectPath', path: '.github/copilot-instructions.md' },
+      { type: 'vscodeExt', prefix: 'github.copilot' },
+      { type: 'bin', name: 'copilot' },
+    ],
+  },
+  {
+    id: 'windsurf',
+    name: 'Windsurf',
+    vendor: 'Codeium',
+    category: CATEGORIES.AI_EDITOR,
+    signals: [
+      { type: 'projectPath', path: '.windsurf' },
+      { type: 'projectPath', path: '.windsurfrules' },
+      { type: 'homePath', path: '.codeium/windsurf' },
+      { type: 'bin', name: 'windsurf' },
+    ],
+  },
+  {
+    id: 'aider',
+    name: 'Aider',
+    vendor: 'Aider AI',
+    category: CATEGORIES.AGENTIC_CLI,
+    signals: [
+      { type: 'projectPath', path: '.aider.conf.yml' },
+      { type: 'projectPath', path: '.aider.chat.history.md' },
+      { type: 'homePath', path: '.aider.conf.yml' },
+      { type: 'bin', name: 'aider' },
+    ],
+  },
+  {
+    id: 'continue',
+    name: 'Continue',
+    vendor: 'Continue',
+    category: CATEGORIES.IDE_ASSISTANT,
+    signals: [
+      { type: 'projectPath', path: '.continue' },
+      { type: 'homePath', path: '.continue' },
+      { type: 'vscodeExt', prefix: 'continue.continue' },
+    ],
+  },
+  {
+    id: 'cline',
+    name: 'Cline',
+    vendor: 'Cline',
+    category: CATEGORIES.IDE_ASSISTANT,
+    signals: [
+      { type: 'projectPath', path: '.clinerules' },
+      { type: 'vscodeExt', prefix: 'saoudrizwan.claude-dev' },
+    ],
+  },
+  {
+    id: 'gemini-cli',
+    name: 'Gemini CLI',
+    vendor: 'Google',
+    category: CATEGORIES.AGENTIC_CLI,
+    signals: [
+      { type: 'projectPath', path: '.gemini' },
+      { type: 'projectPath', path: 'GEMINI.md' },
+      { type: 'homePath', path: '.gemini' },
+      { type: 'bin', name: 'gemini' },
+    ],
+  },
+  {
+    id: 'codex-cli',
+    name: 'Codex CLI',
+    vendor: 'OpenAI',
+    category: CATEGORIES.AGENTIC_CLI,
+    signals: [
+      { type: 'projectPath', path: 'AGENTS.md' },
+      { type: 'homePath', path: '.codex' },
+      { type: 'bin', name: 'codex' },
+    ],
+  },
+  {
+    id: 'cody',
+    name: 'Cody',
+    vendor: 'Sourcegraph',
+    category: CATEGORIES.IDE_ASSISTANT,
+    signals: [
+      { type: 'projectPath', path: '.sourcegraph' },
+      { type: 'vscodeExt', prefix: 'sourcegraph.cody-ai' },
+      { type: 'bin', name: 'cody' },
+    ],
+  },
+  {
+    id: 'zed',
+    name: 'Zed',
+    vendor: 'Zed Industries',
+    category: CATEGORIES.AI_EDITOR,
+    signals: [
+      { type: 'homePath', path: '.config/zed' },
+      { type: 'bin', name: 'zed' },
+    ],
+  },
+  {
+    id: 'tabnine',
+    name: 'Tabnine',
+    vendor: 'Tabnine',
+    category: CATEGORIES.COMPLETION,
+    signals: [
+      { type: 'homePath', path: '.config/TabNine' },
+      { type: 'vscodeExt', prefix: 'tabnine.tabnine-vscode' },
+    ],
+  },
+
+  // ---- Expansion (talents-ai-score, more signals) — confidence per entry below ----
+  {
+    id: 'amazon-q-developer',
+    name: 'Amazon Q Developer',
+    vendor: 'AWS',
+    category: CATEGORIES.AGENTIC_CLI,
+    signals: [
+      // High confidence: binary and extension id are stable for the official CLI/extension.
+      { type: 'bin', name: 'q' },
+      { type: 'vscodeExt', prefix: 'amazonwebservices.amazon-q-vscode' },
+      // Medium confidence: CLI credentials/cache directory under .aws.
+      { type: 'homePath', path: '.aws/amazonq' },
+    ],
+  },
+  {
+    id: 'codeium',
+    name: 'Codeium',
+    vendor: 'Codeium (Exafunction)',
+    category: CATEGORIES.IDE_ASSISTANT,
+    signals: [
+      // Codeium's base extension (autocomplete in any editor), distinct from Windsurf (its own editor, already cataloged above).
+      { type: 'vscodeExt', prefix: 'codeium.codeium' },
+      { type: 'homePath', path: '.codeium/config.json' },
+    ],
+  },
+  {
+    id: 'supermaven',
+    name: 'Supermaven',
+    vendor: 'Supermaven',
+    category: CATEGORIES.COMPLETION,
+    signals: [
+      // High confidence in the extension id; medium in the local state directory.
+      { type: 'vscodeExt', prefix: 'supermaven.supermaven' },
+      { type: 'homePath', path: '.supermaven' },
+    ],
+  },
+  {
+    id: 'pieces',
+    name: 'Pieces for Developers',
+    vendor: 'Mesh Intelligent Technologies',
+    category: CATEGORIES.IDE_ASSISTANT,
+    signals: [
+      // Medium confidence: extension id recalled from memory, could not be verified against the marketplace in this environment.
+      { type: 'vscodeExt', prefix: 'meshintelligenttechnologiesinc.pieces-vscode' },
+    ],
+  },
+  {
+    id: 'warp-ai',
+    name: 'Warp (AI terminal)',
+    vendor: 'Warp',
+    category: CATEGORIES.AI_TERMINAL,
+    signals: [
+      // Medium confidence: config directory of the Warp terminal app.
+      { type: 'homePath', path: '.warp' },
+      // On Linux, Warp's config lives under ~/.config/warp-terminal.
+      { type: 'homePath', path: '.config/warp-terminal' },
+    ],
+  },
+  {
+    id: 'trae',
+    name: 'Trae',
+    vendor: 'ByteDance',
+    category: CATEGORIES.AI_EDITOR,
+    signals: [
+      { type: 'projectPath', path: '.trae' },
+      { type: 'homePath', path: '.trae' },
+      { type: 'bin', name: 'trae' },
+    ],
+  },
+];
+
+module.exports = { detectors, CATEGORIES };

package/src/device-auth-store.js

@@ -0,0 +1,100 @@
+'use strict';
+
+const crypto = require('crypto');
+const fs = require('fs');
+const path = require('path');
+const { getConfigDir } = require('./config-dir');
+
+// `~/.config/shakers/device-auth.json` — bridges the MCP start/poll tools; the secret device_code lives here (0600), never in a tool result.
+
+const DEVICE_FILE_NAME = 'device-auth.json';
+const DEVICE_FILE_VERSION = 1;
+
+function devicePath(env = process.env) {
+  return path.join(getConfigDir(env), DEVICE_FILE_NAME);
+}
+
+// Atomic 0600 write (temp + fsync + rename), same recipe as auth-session-store.
+function savePendingDevice(pending, env = process.env, { fs: fsImpl = fs } = {}) {
+  const payload = `${JSON.stringify(
+    {
+      deviceCode: typeof pending.deviceCode === 'string' && pending.deviceCode ? pending.deviceCode : null,
+      verificationUrl: typeof pending.verificationUrl === 'string' && pending.verificationUrl ? pending.verificationUrl : null,
+      userCode: typeof pending.userCode === 'string' && pending.userCode ? pending.userCode : null,
+      tokenEndpoint: typeof pending.tokenEndpoint === 'string' && pending.tokenEndpoint ? pending.tokenEndpoint : null,
+      authTokenEndpoint: typeof pending.authTokenEndpoint === 'string' && pending.authTokenEndpoint ? pending.authTokenEndpoint : null,
+      interval: typeof pending.interval === 'number' && pending.interval > 0 ? Math.floor(pending.interval) : 5,
+      expiresAt: typeof pending.expiresAt === 'string' && pending.expiresAt ? pending.expiresAt : null,
+      mode: pending.mode === 'register' ? 'register' : 'login',
+      provider: pending.provider === 'linkedin' ? 'linkedin' : 'google',
+      registerContext: pending.registerContext && typeof pending.registerContext === 'object' ? pending.registerContext : null,
+      email: typeof pending.email === 'string' && pending.email ? pending.email : null,
+      version: DEVICE_FILE_VERSION,
+    },
+    null,
+    2,
+  )}\n`;
+
+  const target = devicePath(env);
+  const dir = path.dirname(target);
+  fsImpl.mkdirSync(dir, { recursive: true, mode: 0o700 });
+
+  const tmp = path.join(dir, `.${DEVICE_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 */ } }
+    try { fsImpl.unlinkSync(tmp); } catch { /* never existed */ }
+    throw e;
+  }
+  return target;
+}
+
+function loadPendingDevice(env = process.env, { fs: fsImpl = fs } = {}) {
+  let parsed;
+  try {
+    parsed = JSON.parse(fsImpl.readFileSync(devicePath(env), 'utf8'));
+  } catch {
+    return null;
+  }
+  if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) return null;
+  if (parsed.version !== DEVICE_FILE_VERSION) return null;
+  if (typeof parsed.deviceCode !== 'string' || !parsed.deviceCode) return null;
+  return {
+    deviceCode: parsed.deviceCode,
+    verificationUrl: typeof parsed.verificationUrl === 'string' && parsed.verificationUrl ? parsed.verificationUrl : null,
+    userCode: typeof parsed.userCode === 'string' && parsed.userCode ? parsed.userCode : null,
+    tokenEndpoint: typeof parsed.tokenEndpoint === 'string' && parsed.tokenEndpoint ? parsed.tokenEndpoint : null,
+    authTokenEndpoint: typeof parsed.authTokenEndpoint === 'string' && parsed.authTokenEndpoint ? parsed.authTokenEndpoint : null,
+    interval: typeof parsed.interval === 'number' && parsed.interval > 0 ? Math.floor(parsed.interval) : 5,
+    expiresAt: typeof parsed.expiresAt === 'string' && parsed.expiresAt ? parsed.expiresAt : null,
+    mode: parsed.mode === 'register' ? 'register' : 'login',
+    provider: parsed.provider === 'linkedin' ? 'linkedin' : 'google',
+    registerContext: parsed.registerContext && typeof parsed.registerContext === 'object' ? parsed.registerContext : null,
+    email: typeof parsed.email === 'string' && parsed.email ? parsed.email : null,
+  };
+}
+
+function clearPendingDevice(env = process.env, { fs: fsImpl = fs } = {}) {
+  try {
+    fsImpl.unlinkSync(devicePath(env));
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+module.exports = {
+  DEVICE_FILE_NAME,
+  DEVICE_FILE_VERSION,
+  devicePath,
+  savePendingDevice,
+  loadPendingDevice,
+  clearPendingDevice,
+};

package/src/device-login.js

@@ -0,0 +1,118 @@
+'use strict';
+
+const { requestDeviceAuthorization, requestDeviceToken, requestApiToken } = require('./auth-device-client');
+
+const SLOW_DOWN_STEP_SECONDS = 5;
+const DEFAULT_MAX_WAIT_MS = 15 * 60 * 1000;
+
+function defaultSleep(ms) {
+  // NOT unref'd: the loop's await sleep(...) is the only handle keeping the process alive while it waits.
+  return new Promise((resolve) => { setTimeout(resolve, ms); });
+}
+
+// The /cli-login page reads `provider` from the query to pick the social button.
+function appendProviderParam(url, provider) {
+  if (!url || !provider) return url;
+  try {
+    const u = new URL(url);
+    u.searchParams.set('provider', provider);
+    return u.href;
+  } catch {
+    return `${url}${url.includes('?') ? '&' : '?'}provider=${encodeURIComponent(provider)}`;
+  }
+}
+
+async function startDeviceLogin({ authorizeEndpoint, clientId, scope, timeoutMs } = {}) {
+  return requestDeviceAuthorization({ endpoint: authorizeEndpoint, clientId, scope, timeoutMs });
+}
+
+async function pollDeviceToken({ deviceCode, tokenEndpoint, clientId, timeoutMs } = {}) {
+  return requestDeviceToken({ deviceCode, clientId }, { endpoint: tokenEndpoint, timeoutMs });
+}
+
+// ORDER: a NEW user needs complete-registration BEFORE GET /auth/token (else the Hub 500s: no domain user).
+async function finalizeDeviceSession(
+  { sessionToken, isNewUser, authTokenEndpoint, completeRegistrationEndpoint = null, registrationContext = null, timeoutMs } = {},
+  {
+    requestCompleteRegistration = require('./signup-client').requestCompleteRegistration,
+    requestApiToken: apiToken = requestApiToken,
+  } = {},
+) {
+  if (!authTokenEndpoint) return { ok: false, reason: 'no-endpoint' };
+
+  if (isNewUser && completeRegistrationEndpoint) {
+    const done = await requestCompleteRegistration(registrationContext || {}, { endpoint: completeRegistrationEndpoint, bearerToken: sessionToken, timeoutMs });
+    if (!done.ok) return { ok: false, reason: done.reason || 'complete-registration-failed' };
+  }
+
+  const jwt = await apiToken({ accessToken: sessionToken }, { endpoint: authTokenEndpoint, timeoutMs });
+  if (!jwt.ok) return { ok: false, reason: 'token-exchange-failed' };
+  return { ok: true, token: jwt.token };
+}
+
+async function runDeviceLogin(
+  { authorizeEndpoint, tokenEndpoint, authTokenEndpoint, completeRegistrationEndpoint = null, registrationContext = null, clientId, scope, timeoutMs } = {},
+  {
+    onPrompt = null,
+    onWaiting = null,
+    sleep = defaultSleep,
+    now = () => Date.now(),
+    maxWaitMs = DEFAULT_MAX_WAIT_MS,
+  } = {},
+) {
+  if (!authorizeEndpoint || !tokenEndpoint || !authTokenEndpoint) return { ok: false, reason: 'no-endpoint' };
+
+  const authz = await startDeviceLogin({ authorizeEndpoint, clientId, scope, timeoutMs });
+  if (!authz.ok) return { ok: false, reason: authz.reason || 'authorize-failed' };
+
+  if (typeof onPrompt === 'function') {
+    onPrompt({
+      verificationUriComplete: authz.verificationUriComplete,
+      verificationUri: authz.verificationUri,
+      userCode: authz.userCode,
+      expiresIn: authz.expiresIn,
+    });
+  }
+
+  let intervalSeconds = authz.interval;
+  const deadline = now() + Math.min(authz.expiresIn * 1000, maxWaitMs);
+
+  for (;;) {
+    if (now() >= deadline) return { ok: false, reason: 'expired' };
+    if (typeof onWaiting === 'function') onWaiting();
+    await sleep(intervalSeconds * 1000);
+
+    const res = await pollDeviceToken({ deviceCode: authz.deviceCode, tokenEndpoint, clientId, timeoutMs });
+    if (res.status === 'authorized') {
+      const fin = await finalizeDeviceSession({
+        sessionToken: res.accessToken,
+        isNewUser: res.isNewUser,
+        authTokenEndpoint,
+        completeRegistrationEndpoint,
+        registrationContext,
+        timeoutMs,
+      });
+      if (!fin.ok) return { ok: false, reason: fin.reason };
+      return { ok: true, token: fin.token, sessionToken: res.accessToken, isNewUser: res.isNewUser, email: res.email || null };
+    }
+    if (res.status === 'pending') continue;
+    if (res.status === 'slow_down') {
+      intervalSeconds += SLOW_DOWN_STEP_SECONDS;
+      continue;
+    }
+    if (res.status === 'denied') return { ok: false, reason: 'denied' };
+    if (res.status === 'expired') return { ok: false, reason: 'expired' };
+    return { ok: false, reason: res.reason || 'poll-failed' };
+  }
+}
+
+module.exports = {
+  startDeviceLogin,
+  pollDeviceToken,
+  finalizeDeviceSession,
+  runDeviceLogin,
+  appendProviderParam,
+  defaultSleep,
+  SLOW_DOWN_STEP_SECONDS,
+  DEFAULT_MAX_WAIT_MS,
+};

package/src/email-verification.js

@@ -0,0 +1,152 @@
+'use strict';
+
+const { requestBackend } = require('./backend-request');
+
+// Email-verification client + wait-mode loop (skill-code-certification, ADR-006).
+
+const DEFAULT_TIMEOUT_MS = 15000;
+// Bounded so a Talent who can never produce a matching code can't loop forever — after this many CODE-ENTRY attempts we give up (nothing persisted, asked again next run).
+const MAX_CODE_ATTEMPTS = 5;
+
+// POST {email} to the request endpoint.
+async function requestCode({ email }, { url, timeoutMs = DEFAULT_TIMEOUT_MS } = {}) {
+  if (!url) return { ok: false, reason: 'no-endpoint' };
+
+  let res;
+  try {
+    res = await requestBackend({ endpoint: url, body: { email }, timeoutMs });
+  } catch (e) {
+    if (e && e.kind === 'timeout') return { ok: false, reason: 'timeout' };
+    return { ok: false, reason: 'network-error', detail: e && e.message };
+  }
+
+  if (res.status < 200 || res.status >= 300) {
+    return { ok: false, reason: `http-${res.status}` };
+  }
+  return { ok: true, backend: res.backend };
+}
+
+// Maps a server "not verified" outcome to a soft reason the loop can retry on.
+function mapNotVerifiedReason(bodyReason) {
+  return bodyReason === 'expired' ? 'expired' : 'invalid-code';
+}
+
+// POST {email, code} to the verify endpoint.
+async function verifyCode({ email, code }, { url, timeoutMs = DEFAULT_TIMEOUT_MS } = {}) {
+  if (!url) return { ok: false, reason: 'no-endpoint' };
+
+  let res;
+  try {
+    res = await requestBackend({ endpoint: url, body: { email, code }, timeoutMs });
+  } catch (e) {
+    if (e && e.kind === 'timeout') return { ok: false, reason: 'timeout' };
+    return { ok: false, reason: 'network-error', detail: e && e.message };
+  }
+
+  let parsed = null;
+  try {
+    parsed = res.raw ? JSON.parse(res.raw) : null;
+  } catch {
+    // fall through: unparseable body handled per status below
+  }
+
+  if (res.status >= 200 && res.status < 300) {
+    if (parsed && parsed.verified === true) return { ok: true, verified: true, backend: res.backend };
+    if (parsed && typeof parsed === 'object') return { ok: false, reason: mapNotVerifiedReason(parsed.reason) };
+    return { ok: false, reason: 'invalid-json' };
+  }
+
+  // Non-2xx: a bad/expired code the server rejects at the HTTP layer is still
+  // a SOFT failure (retryable). 5xx and anything else is technical.
+  if (res.status === 400 || res.status === 401 || res.status === 410 || res.status === 422) {
+    return { ok: false, reason: mapNotVerifiedReason(parsed && parsed.reason) };
+  }
+  return { ok: false, reason: `http-${res.status}` };
+}
+
+// Categorizes a verifyCode reason for the wait-mode loop: 'soft' -> invalid/expired code: show a message, keep waiting (retry).
+function classifyVerifyReason(reason) {
+  if (reason === 'invalid-code' || reason === 'expired') return 'soft';
+  return 'technical';
+}
+
+// The interactive "modo espera": send a code, then loop reading the pasted code until it verifies, the Talent cancels, or attempts run out.
+// talents-ai-score, ADR-042: `requestUrl`/`verifyUrl` address the ONE backend (the certifications service).
+async function runEmailVerification({
+  email,
+  ask,
+  catalog,
+  requestUrl,
+  verifyUrl,
+  deps = {},
+}) {
+  const v = catalog.verify;
+  const doRequest = deps.requestCode || requestCode;
+  const doVerify = deps.verifyCode || verifyCode;
+  const write = deps.write || ((s) => process.stdout.write(s));
+
+  // No endpoint could be derived (ingest unset): nothing to verify against,
+  // and nowhere to persist either. Quiet, non-error outcome.
+  if (!requestUrl || !verifyUrl) {
+    write(`  ${v.unavailable}\n`);
+    return { verified: false, reason: 'unavailable' };
+  }
+
+  const sent = await doRequest({ email }, { url: requestUrl });
+  if (!sent.ok) {
+    write(`  ${v.requestFailed}\n`);
+    return { verified: false, reason: 'request-failed' };
+  }
+
+  // Entered wait mode.
+  write(`\n  ${v.sent(email)}\n`);
+  write(`  ${v.waitHint}\n`);
+
+  for (let attempt = 0; attempt < MAX_CODE_ATTEMPTS; ) {
+    // The OTP is a secret too (issue 102): same reader, same echo, and the fix is the same call.
+    const readCode = typeof ask.secret === 'function' ? ask.secret.bind(ask) : ask;
+    const raw = String(await readCode(v.codePrompt)).trim();
+
+    // Empty line / EOF (piped, closed stdin) / Ctrl-C-then-Enter -> cancel.
+    if (raw === '') {
+      write(`  ${v.cancelled}\n`);
+      return { verified: false, reason: 'cancelled' };
+    }
+
+    // Resend, without consuming an attempt.
+    if (/^r$/i.test(raw)) {
+      const resent = await doRequest({ email }, { url: requestUrl });
+      write(resent.ok ? `  ${v.resent(email)}\n` : `  ${v.resendFailed}\n`);
+      continue;
+    }
+
+    attempt++;
+    const result = await doVerify({ email, code: raw }, { url: verifyUrl });
+    if (result.ok && result.verified) {
+      write(`  ${v.verified}\n`);
+      return { verified: true, backend: result.backend };
+    }
+
+    if (classifyVerifyReason(result.reason) === 'soft') {
+      write(result.reason === 'expired' ? `  ${v.expired}\n` : `  ${v.invalidCode}\n`);
+      continue;
+    }
+
+    // Technical: the Hub couldn't be reached or answered unexpectedly. Legible
+    // error, bail out (nothing persisted); the report was already shown.
+    write(`  ${v.technicalError}\n`);
+    return { verified: false, reason: 'technical' };
+  }
+
+  write(`  ${v.tooManyAttempts}\n`);
+  return { verified: false, reason: 'exhausted' };
+}
+
+module.exports = {
+  requestCode,
+  verifyCode,
+  classifyVerifyReason,
+  runEmailVerification,
+  DEFAULT_TIMEOUT_MS,
+  MAX_CODE_ATTEMPTS,
+};

package/src/env-paths.js

@@ -0,0 +1,16 @@
+'use strict';
+
+const os = require('os');
+
+// Shared home-directory + env resolution (talents-ai-score, ADR-014 — "Alcance del tier: Talento = proyecto ∪ home", applied uniformly to every category).
+function readEnv(env, suffix) {
+  const next = env[`SHAKERS_CLI_${suffix}`];
+  if (next !== undefined && next !== '') return next;
+  return env[`AI_FOOTPRINT_${suffix}`];
+}
+
+function getHomeDir(env = process.env) {
+  return readEnv(env, 'HOME_DIR') || os.homedir();
+}
+
+module.exports = { getHomeDir, readEnv };