shakers-cli-beta 0.8.0-beta.0

package/src/mcp-role-tools.js

@@ -0,0 +1,112 @@
+'use strict';
+
+// MCP: role/cluster management — list addable roles, add one, list held roles,
+// and set the main role. The onboarding final step is set_main_role after the
+// interview (or after skipping it).
+
+const EMPTY_SCHEMA = { type: 'object', properties: {} };
+
+const CLUSTER_SCHEMA = {
+  type: 'object',
+  properties: {
+    clusterId: { type: 'string', description: 'The role clusterId from list_available_roles / list_my_roles. Internal handle — refer to the role by its name to the talent, never show the id.' },
+  },
+  required: ['clusterId'],
+};
+
+function makeRoleTools(deps = {}) {
+  const {
+    getAvailableRolesEndpoint = require('./config').getAvailableRolesEndpoint,
+    getSetMainRoleEndpoint = require('./config').getSetMainRoleEndpoint,
+    getAssignedClustersEndpoint = require('./config').getAssignedClustersEndpoint,
+    getMyCertificationsEndpoint = require('./config').getMyCertificationsEndpoint,
+    requestAvailableRoles = require('./roles-client').requestAvailableRoles,
+    requestAssignedClusters = require('./roles-client').requestAssignedClusters,
+    requestAddGrowthRole = require('./roles-client').requestAddGrowthRole,
+    requestSetMainRole = require('./roles-client').requestSetMainRole,
+    requestMeCertifications = require('./certifications-client').requestMeCertifications,
+    loadAuthSession = require('./auth-session-store').loadAuthSession,
+    sessionStatus = require('./auth-session-store').sessionStatus,
+    dedupeByCluster = require('./roles-flow').dedupeByCluster,
+  } = deps;
+
+  const requireSession = () => {
+    const session = loadAuthSession();
+    if (sessionStatus(session) !== 'active') {
+      throw new Error('no active Shakers session — call the login tool (or run `shakers login`) first.');
+    }
+    return session;
+  };
+
+  const shape = (r) => ({ clusterId: r.clusterId, name: r.name, category: r.category, ...(r.proposalKind ? { proposalKind: r.proposalKind } : {}) });
+
+  async function listAvailableRoles() {
+    const session = requireSession();
+    const res = await requestAvailableRoles({ hubAccessToken: session.hubAccessToken }, { endpoint: getAvailableRolesEndpoint() });
+    if (!res.ok) return { ok: false, reason: res.reason };
+    return { ok: true, roles: dedupeByCluster(res.roles).map(shape) };
+  }
+
+  async function addRole(args = {}) {
+    const session = requireSession();
+    if (!args.clusterId) return { ok: false, reason: 'no-cluster' };
+    const res = await requestAddGrowthRole({ clusterId: args.clusterId, hubAccessToken: session.hubAccessToken }, { endpoint: getAssignedClustersEndpoint() });
+    if (!res.ok) {
+      if (res.reason === 'already-assigned') return { ok: true, clusterId: args.clusterId, alreadyAssigned: true };
+      return { ok: false, reason: res.reason };
+    }
+    return { ok: true, clusterId: args.clusterId };
+  }
+
+  async function listMyRoles() {
+    const session = requireSession();
+    const hubAccessToken = session.hubAccessToken;
+    const held = [];
+    let mainClusterId = null;
+    const cert = await requestMeCertifications({ hubAccessToken }, { endpoint: getMyCertificationsEndpoint() });
+    if (cert.ok) {
+      if (cert.mainRole && cert.mainRole.clusterId) { held.push(cert.mainRole); mainClusterId = cert.mainRole.clusterId; }
+      for (const g of cert.growingInto || []) held.push(g);
+    }
+    const assigned = await requestAssignedClusters({ hubAccessToken }, { endpoint: getAssignedClustersEndpoint() });
+    if (assigned.ok) for (const c of assigned.clusters || []) held.push(c);
+    return { ok: true, mainClusterId, roles: dedupeByCluster(held).map(shape) };
+  }
+
+  async function setMainRole(args = {}) {
+    const session = requireSession();
+    if (!args.clusterId) return { ok: false, reason: 'no-cluster' };
+    const res = await requestSetMainRole({ clusterId: args.clusterId, hubAccessToken: session.hubAccessToken }, { endpoint: getSetMainRoleEndpoint() });
+    if (!res.ok) return { ok: false, reason: res.reason };
+    return { ok: true, clusterId: args.clusterId };
+  }
+
+  return [
+    {
+      name: 'list_available_roles',
+      description: "List the roles the talent can add to their profile (the cluster catalog minus roles they already hold). Each row has clusterId (internal handle), name, category and an optional proposalKind (why it is suggested). Present roles to the talent by NAME; never show clusterId. Requires an active session.",
+      inputSchema: EMPTY_SCHEMA,
+      handler: listAvailableRoles,
+    },
+    {
+      name: 'add_role',
+      description: "Add a role to the talent's profile (a GROWTH role) by clusterId from list_available_roles. Requires an active session. Returns { clusterId, alreadyAssigned? }.",
+      inputSchema: CLUSTER_SCHEMA,
+      handler: addRole,
+    },
+    {
+      name: 'list_my_roles',
+      description: "List the roles the talent already holds, plus mainClusterId (their current main role). Use it before set_main_role. clusterId is an internal handle — refer to roles by name to the talent. Requires an active session.",
+      inputSchema: EMPTY_SCHEMA,
+      handler: listMyRoles,
+    },
+    {
+      name: 'set_main_role',
+      description: "Set the talent's MAIN role to one they already hold, by clusterId from list_my_roles. This is the onboarding FINAL step: after onboarding_interview_complete (or if the talent skipped the interview), offer them their held roles and set the one they pick. Also usable standalone to change the main role later. Requires an active session.",
+      inputSchema: CLUSTER_SCHEMA,
+      handler: setMainRole,
+    },
+  ];
+}
+
+module.exports = { makeRoleTools, EMPTY_SCHEMA, CLUSTER_SCHEMA };

package/src/mcp-saved-positions-tools.js

@@ -0,0 +1,55 @@
+'use strict';
+
+// MCP: bookmark / un-bookmark a Position. Both idempotent, reversible, low-risk.
+
+const ID_SCHEMA = {
+  type: 'object',
+  properties: { id: { type: 'string', description: 'Position id (UUID) — an internal handle from a prior list; never shown or mentioned to the talent.' } },
+  required: ['id'],
+};
+
+function makeSavedPositionsTools(deps = {}) {
+  const {
+    savePosition = (opts) => require('./saved-positions-client').savePosition({}, opts),
+    unsavePosition = (opts) => require('./saved-positions-client').unsavePosition({}, opts),
+    loadAuthSession = require('./auth-session-store').loadAuthSession,
+    sessionStatus = require('./auth-session-store').sessionStatus,
+  } = deps;
+
+  const requireLoginSession = () => {
+    const session = loadAuthSession();
+    if (sessionStatus(session) !== 'active') {
+      throw new Error('no active Shakers session — call the login tool (or run `shakers login`) first (this tool is session-gated).');
+    }
+    return session;
+  };
+
+  const toggle = (op) => async (args = {}) => {
+    const session = requireLoginSession();
+    const positionId = typeof args.id === 'string' ? args.id.trim() : null;
+    if (!positionId) return { ok: false, reason: 'no-id' };
+    const res = await op({ hubAccessToken: session.hubAccessToken, positionId });
+    if (!res.ok) return { ok: false, reason: res.reason };
+    return { ok: true, positionId };
+  };
+
+  return [
+    {
+      name: 'save_project',
+      description: 'Bookmark a project/Position for the talent (Find Positions "Saved"). Idempotent — saving twice is a no-op. Requires an active session and the position id. The position id is an INTERNAL handle for calling tools — never show or mention it to the talent.',
+      inputSchema: ID_SCHEMA,
+      handler: toggle(savePosition),
+    },
+    {
+      name: 'unsave_project',
+      description: 'Remove a project/Position bookmark for the talent. Idempotent — un-saving something not saved is not an error. Requires an active session and the position id. The position id is an INTERNAL handle for calling tools — never show or mention it to the talent.',
+      inputSchema: ID_SCHEMA,
+      handler: toggle(unsavePosition),
+    },
+  ];
+}
+
+module.exports = {
+  makeSavedPositionsTools,
+  ID_SCHEMA,
+};

package/src/mcp-server.js

@@ -0,0 +1,170 @@
+'use strict';
+
+const readline = require('readline');
+
+const JSONRPC = '2.0';
+const DEFAULT_PROTOCOL_VERSION = '2025-06-18';
+
+const ERROR = {
+  PARSE: -32700,
+  INVALID_REQUEST: -32600,
+  METHOD_NOT_FOUND: -32601,
+  INVALID_PARAMS: -32602,
+  INTERNAL: -32603,
+};
+
+function isNotification(msg) {
+  return !msg || msg.id === undefined || msg.id === null;
+}
+
+function resultResponse(id, result) {
+  return { jsonrpc: JSONRPC, id, result };
+}
+
+function errorResponse(id, code, message, data) {
+  const error = { code, message };
+  if (data !== undefined) error.data = data;
+  return { jsonrpc: JSONRPC, id: id === undefined ? null : id, error };
+}
+
+function createMcpServer({ tools = [], serverInfo = {}, protocolVersion, beforeCall = null } = {}) {
+  const registry = new Map();
+  for (const t of tools) {
+    if (!t || !t.name || typeof t.handler !== 'function') {
+      throw new Error('each tool needs a name and a handler function');
+    }
+    registry.set(t.name, t);
+  }
+
+  const advertisedVersion = protocolVersion || DEFAULT_PROTOCOL_VERSION;
+
+  function shapeTool(t) {
+    return {
+      name: t.name,
+      description: t.description || '',
+      inputSchema: t.inputSchema || { type: 'object' },
+    };
+  }
+
+  function listTools() {
+    return { tools: [...registry.values()].map(shapeTool) };
+  }
+
+  async function listAvailableTools() {
+    const out = [];
+    for (const t of registry.values()) {
+      if (typeof t.available === 'function') {
+        let visible = true;
+        try {
+          visible = (await t.available()) !== false;
+        } catch {
+          visible = true;
+        }
+        if (!visible) continue;
+      }
+      out.push(shapeTool(t));
+    }
+    return { tools: out };
+  }
+
+  async function callTool(params) {
+    const name = params && params.name;
+    const tool = name && registry.get(name);
+    if (!tool) {
+      const err = new Error(`unknown tool: ${name}`);
+      err.rpcCode = ERROR.INVALID_PARAMS;
+      throw err;
+    }
+    const args = (params && params.arguments) || {};
+    // Optional per-call hook (auth-agnostic): the MCP server is long-lived, so this is where the email session's hub JWT gets refreshed before each tool runs.
+    if (typeof beforeCall === 'function') {
+      try { await beforeCall(name); } catch { /* hook must never break a tool call */ }
+    }
+    try {
+      const value = await tool.handler(args);
+      return {
+        content: [{ type: 'text', text: JSON.stringify(value, null, 2) }],
+        isError: false,
+      };
+    } catch (e) {
+      return {
+        content: [{ type: 'text', text: `${name} tool error: ${e && e.message ? e.message : String(e)}` }],
+        isError: true,
+      };
+    }
+  }
+
+  async function handleMessage(msg) {
+    if (!msg || msg.jsonrpc !== JSONRPC || typeof msg.method !== 'string') {
+      if (isNotification(msg)) return null;
+      return errorResponse(msg && msg.id, ERROR.INVALID_REQUEST, 'invalid JSON-RPC request');
+    }
+
+    const { method, id } = msg;
+
+    if (method.startsWith('notifications/')) {
+      return null;
+    }
+
+    try {
+      switch (method) {
+        case 'initialize': {
+          const requested = msg.params && msg.params.protocolVersion;
+          return resultResponse(id, {
+            protocolVersion: requested || advertisedVersion,
+            capabilities: { tools: { listChanged: false } },
+            serverInfo: {
+              name: serverInfo.name || 'shakers-mcp',
+              version: serverInfo.version || '0.0.0',
+            },
+          });
+        }
+        case 'ping':
+          return resultResponse(id, {});
+        case 'tools/list':
+          return resultResponse(id, await listAvailableTools());
+        case 'tools/call':
+          return resultResponse(id, await callTool(msg.params));
+        default:
+          if (isNotification(msg)) return null;
+          return errorResponse(id, ERROR.METHOD_NOT_FOUND, `method not found: ${method}`);
+      }
+    } catch (e) {
+      if (isNotification(msg)) return null;
+      const code = (e && e.rpcCode) || ERROR.INTERNAL;
+      return errorResponse(id, code, e && e.message ? e.message : 'internal error');
+    }
+  }
+
+  function start({ input = process.stdin, output = process.stdout, onError } = {}) {
+    const rl = readline.createInterface({ input, crlfDelay: Infinity });
+    const write = (obj) => output.write(`${JSON.stringify(obj)}\n`);
+
+    rl.on('line', async (line) => {
+      const trimmed = line.trim();
+      if (!trimmed) return;
+      let msg;
+      try {
+        msg = JSON.parse(trimmed);
+      } catch {
+        write(errorResponse(null, ERROR.PARSE, 'parse error: invalid JSON'));
+        return;
+      }
+      try {
+        const response = await handleMessage(msg);
+        if (response) write(response);
+      } catch (e) {
+        if (onError) onError(e);
+        if (!isNotification(msg)) {
+          write(errorResponse(msg.id, ERROR.INTERNAL, e && e.message ? e.message : 'internal error'));
+        }
+      }
+    });
+
+    return rl;
+  }
+
+  return { handleMessage, listTools, listAvailableTools, callTool, start };
+}
+
+module.exports = { createMcpServer, ERROR, DEFAULT_PROTOCOL_VERSION };

package/src/mcp-show-project-tools.js

@@ -0,0 +1,50 @@
+'use strict';
+
+// MCP: detail of one Position/Project (Find Positions detail view).
+
+const SHOW_PROJECT_SCHEMA = {
+  type: 'object',
+  properties: {
+    id: { type: 'string', description: 'Position id (UUID or legacy Mongo id) — an internal handle from a prior list; never shown to the talent.' },
+  },
+  required: ['id'],
+};
+
+function makeShowProjectTools(deps = {}) {
+  const {
+    fetchPositionDetail = (opts) => require('./show-project-client').fetchPositionDetail({}, opts),
+    loadAuthSession = require('./auth-session-store').loadAuthSession,
+    sessionStatus = require('./auth-session-store').sessionStatus,
+  } = deps;
+
+  const requireLoginSession = () => {
+    const session = loadAuthSession();
+    if (sessionStatus(session) !== 'active') {
+      throw new Error('no active Shakers session — call the login tool (or run `shakers login`) first (show_project is session-gated).');
+    }
+    return session;
+  };
+
+  async function showProject(args = {}) {
+    const session = requireLoginSession();
+    const positionId = typeof args.id === 'string' ? args.id.trim() : null;
+    if (!positionId) return { ok: false, reason: 'no-id' };
+    const res = await fetchPositionDetail({ hubAccessToken: session.hubAccessToken, positionId });
+    if (!res.ok) return { ok: false, reason: res.reason };
+    return { ok: true, position: res.position, redirectUrl: res.redirectUrl };
+  }
+
+  return [
+    {
+      name: 'show_project',
+      description: "Get the full detail of one Position/Project available to the talent (Shakers Find Positions detail): title, parent project, company, budget, work mode, required skills/languages, description, goals, FAQs, and the talent's saved/applied/canApply state. Requires an active session and the position id. The `id` (and any positionId/projectId in the result) is an INTERNAL handle for calling tools — NEVER show or mention it to the talent; refer to the project by its title/company.",
+      inputSchema: SHOW_PROJECT_SCHEMA,
+      handler: showProject,
+    },
+  ];
+}
+
+module.exports = {
+  makeShowProjectTools,
+  SHOW_PROJECT_SCHEMA,
+};

package/src/mcp-socials-tools.js

@@ -0,0 +1,39 @@
+'use strict';
+
+// MCP: view the talent's social links. Read-only (editing is CLI-only).
+
+const LIST_SOCIALS_SCHEMA = { type: 'object', properties: {} };
+
+function makeSocialsTools(deps = {}) {
+  const {
+    fetchSocials = (opts) => require('./socials-client').fetchSocials({}, opts),
+    loadAuthSession = require('./auth-session-store').loadAuthSession,
+    sessionStatus = require('./auth-session-store').sessionStatus,
+  } = deps;
+
+  const requireLoginSession = () => {
+    const session = loadAuthSession();
+    if (sessionStatus(session) !== 'active') {
+      throw new Error('no active Shakers session — call the login tool (or run `shakers login`) first (list_socials is session-gated).');
+    }
+    return session;
+  };
+
+  async function listSocials() {
+    const session = requireLoginSession();
+    const res = await fetchSocials({ hubAccessToken: session.hubAccessToken });
+    if (!res.ok) return { ok: false, reason: res.reason };
+    return { ok: true, social: res.social };
+  }
+
+  return [
+    {
+      name: 'list_socials',
+      description: "View the talent's social links (linkedin/github/website/twitter/instagram/facebook/dribbble/behance — null when unset). Read-only. Requires an active session.",
+      inputSchema: LIST_SOCIALS_SCHEMA,
+      handler: listSocials,
+    },
+  ];
+}
+
+module.exports = { makeSocialsTools, LIST_SOCIALS_SCHEMA };

package/src/memory-structure-detector.js

@@ -0,0 +1,108 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const { getHomeDir } = require('./env-paths');
+
+// Deterministic (no-LLM) memory STRUCTURE detector (talents-ai-score, issue 016 / ADR-013-014).
+
+const MAX_FILE_BYTES = 2_000_000; // safety cap: never read a pathologically huge file
+const MAX_IMPORT_DEPTH = 5; // mirrors Claude Code's own documented import-hop limit
+const MAX_FILES_VISITED = 100; // safety cap against import fan-out/cycles
+
+// Claude Code's `@path/to/file` import syntax: an `@` at the start of a line or preceded by whitespace, followed by a non-space path.
+const IMPORT_RE = /(?:^|\s)@(\S+)/gm;
+const HEADER_RE = /^#{1,6}\s+\S/gm;
+
+function safeReadText(file) {
+  try {
+    const st = fs.statSync(file);
+    if (!st.isFile() || st.size > MAX_FILE_BYTES) return null;
+    return fs.readFileSync(file, 'utf8');
+  } catch {
+    return null;
+  }
+}
+
+function countMatches(re, text) {
+  const matches = text.match(re);
+  return matches ? matches.length : 0;
+}
+
+function extractImportPaths(text) {
+  const paths = [];
+  const re = new RegExp(IMPORT_RE);
+  let m;
+  while ((m = re.exec(text)) !== null) paths.push(m[1]);
+  return paths;
+}
+
+function resolveImportPath(importPath, fromDir, home) {
+  if (importPath.startsWith('~/')) return path.join(home, importPath.slice(2));
+  return path.resolve(fromDir, importPath);
+}
+
+// Recursively walks `@imports` starting at `file`.
+function walkImports(file, home, depth, visited, budget) {
+  if (depth > MAX_IMPORT_DEPTH || visited.has(file) || budget.files >= MAX_FILES_VISITED) {
+    return { maxDepth: depth - 1, importCount: 0 };
+  }
+  visited.add(file);
+  budget.files += 1;
+
+  const text = safeReadText(file);
+  if (text === null) return { maxDepth: depth - 1, importCount: 0 };
+
+  const importPaths = extractImportPaths(text);
+  if (importPaths.length === 0) return { maxDepth: depth, importCount: 0 };
+
+  let maxDepth = depth;
+  let importCount = importPaths.length;
+  const fromDir = path.dirname(file);
+  for (const p of importPaths) {
+    const resolved = resolveImportPath(p, fromDir, home);
+    const sub = walkImports(resolved, home, depth + 1, visited, budget);
+    maxDepth = Math.max(maxDepth, sub.maxDepth);
+    importCount += sub.importCount;
+  }
+  return { maxDepth, importCount };
+}
+
+function analyzeFile(file, home) {
+  const text = safeReadText(file);
+  if (text === null) return null;
+  const sections = countMatches(HEADER_RE, text);
+  const sizeBytes = Buffer.byteLength(text, 'utf8');
+  const { maxDepth, importCount } = walkImports(file, home, 1, new Set(), { files: 0 });
+  return { sizeBytes, sections, imports: importCount, depth: maxDepth };
+}
+
+function knownContextFiles(root, home) {
+  return [
+    { id: 'CLAUDE.md', file: path.join(root, 'CLAUDE.md') },
+    { id: 'CLAUDE.md (home)', file: path.join(home, '.claude', 'CLAUDE.md') },
+    { id: 'AGENTS.md', file: path.join(root, 'AGENTS.md') },
+    { id: 'GEMINI.md', file: path.join(root, 'GEMINI.md') },
+  ];
+}
+
+// Deterministic (no-LLM) memory structure analysis, scoped to known context files (project ∪ home).
+function analyzeMemoryStructure(root) {
+  const home = getHomeDir();
+  const files = [];
+  let totalImports = 0;
+  let maxDepth = 0;
+
+  for (const { id, file } of knownContextFiles(root, home)) {
+    const analysis = analyzeFile(file, home);
+    if (!analysis) continue;
+    files.push({ id, ...analysis });
+    totalImports += analysis.imports;
+    maxDepth = Math.max(maxDepth, analysis.depth);
+  }
+
+  // "layered" (anidada/por capas) means a REAL import chain — an import that itself imports further files — not just a single flat `@import`.
+  return { files, totalImports, maxDepth, layered: maxDepth > 2 };
+}
+
+module.exports = { analyzeMemoryStructure };