shakers-cli-beta 0.8.0-beta.0

package/src/mcp-ai-usage-tool.js

@@ -0,0 +1,333 @@
+'use strict';
+
+const fs = require('fs');
+const { execFileSync } = require('child_process');
+const { isRefusedWalkRoot } = require('./scan-exclusions');
+
+function isExistingDir(p) {
+  try {
+    return fs.statSync(p).isDirectory();
+  } catch {
+    return false;
+  }
+}
+
+function defaultCwdIsRepo(cwd) {
+  try {
+    execFileSync('git', ['-C', cwd, 'rev-parse', '--show-toplevel'], {
+      stdio: ['ignore', 'ignore', 'ignore'],
+      timeout: 5000,
+    });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+const AI_USAGE_INPUT_SCHEMA = {
+  type: 'object',
+  properties: {
+    consent: {
+      type: 'object',
+      description:
+        'Talent consent to persist the AI-usage report to Shakers. Ask the user in the chat before calling; do not assume it. When granted, an email is required.',
+      properties: {
+        granted: { type: 'boolean', description: 'Whether the talent granted consent to send the report.' },
+        email: { type: 'string', description: 'The talent email the report is attributed to. Required when granted is true.' },
+      },
+      required: ['granted'],
+    },
+    repoScope: {
+      type: 'object',
+      description: 'Which repositories feed the evaluation. Defaults to the current repository only.',
+      properties: {
+        mode: {
+          type: 'string',
+          enum: ['current', 'all', 'list'],
+          description: "'current' = only the repo at root; 'all' = machine-wide session signals; 'list' = the repos named in `repos`.",
+        },
+        repos: {
+          type: 'array',
+          items: { type: 'string' },
+          description: "Repo names or paths, used only when mode is 'list'.",
+        },
+      },
+    },
+    root: {
+      type: 'string',
+      description: 'Absolute path to the repository to evaluate. Defaults to the server working directory.',
+    },
+    lang: { type: 'string', enum: ['es', 'en'], description: 'Report language.' },
+  },
+};
+
+async function defaultCaptureStdout(fn) {
+  const chunks = [];
+  const original = process.stdout.write.bind(process.stdout);
+  process.stdout.write = (chunk, encoding, cb) => {
+    chunks.push(typeof chunk === 'string' ? chunk : chunk.toString(encoding || 'utf8'));
+    if (typeof encoding === 'function') encoding();
+    else if (typeof cb === 'function') cb();
+    return true;
+  };
+  try {
+    await fn();
+  } finally {
+    process.stdout.write = original;
+  }
+  return chunks.join('');
+}
+
+function parseReportJson(captured) {
+  const text = captured || '';
+  try {
+    return JSON.parse(text.trim());
+  } catch {
+    const start = text.indexOf('{');
+    if (start === -1) {
+      throw new Error('ai-usage --json produced no JSON document on stdout');
+    }
+    return JSON.parse(text.slice(start));
+  }
+}
+
+function buildArgv({ root, repoScope, lang }) {
+  const argv = ['--json', '--no-save', '--no-ai'];
+  if (root) argv.push('--root', root);
+  const mode = repoScope && repoScope.mode;
+  if (mode === 'all') {
+    argv.push('--all-repos');
+  } else if (mode === 'list' && Array.isArray(repoScope.repos) && repoScope.repos.length > 0) {
+    argv.push('--repos', repoScope.repos.join(','));
+  }
+  if (lang === 'es' || lang === 'en') argv.push('--lang', lang);
+  return argv;
+}
+
+function makeAiUsageTool(deps = {}) {
+  const {
+    runAiUsage = require('../bin/ai-usage').run,
+    autoShare = require('./share').autoShare,
+    recordConsent = require('./share').recordConsent,
+    isValidEmail = require('./share').isValidEmail,
+    persistFootprint = require('./report-store').persistFootprint,
+    captureStdout = defaultCaptureStdout,
+    cwdIsRepo = defaultCwdIsRepo,
+    loadAuthSession = require('./auth-session-store').loadAuthSession,
+    sessionStatus = require('./auth-session-store').sessionStatus,
+    getUsageDiscoveredInventoryEndpoint = require('./config').getUsageDiscoveredInventoryEndpoint,
+    requestDiscoveredInventory = require('./inventory-client').requestDiscoveredInventory,
+    pollClassifiedInventory = require('./mcp-ai-usage-result-tool').pollClassifiedInventory,
+    tierLadder = require('./tier-engine').tierLadder,
+    inlineWaitMs = 35000,
+    // "My work with AI" preview, from the same hub endpoint the front paints.
+    resolveAiProfilePreview = require('./ai-profile-preview').resolveAiProfilePreview,
+    ensureFreshSession = require('./session-refresh').ensureFreshSession,
+    getAiProfileEndpoint = require('./config').getAiProfileEndpoint,
+    // Plain-text render of the full report (terminal sections + matrix/vision/howIWork), shared with the CLI (no ANSI).
+    renderFullReportText = require('./render-report-text').renderFullReportText,
+    detectFlowLang = require('./i18n').detectFlowLang,
+    aiFluencyWaitMs = 30000,
+  } = deps;
+
+  async function handler(args = {}) {
+    const mode = (args.repoScope && args.repoScope.mode) || 'current';
+    const lang = args.lang === 'es' || args.lang === 'en' ? args.lang : detectFlowLang();
+
+    let root;
+    if (typeof args.root === 'string' && args.root) {
+      if (!isExistingDir(args.root)) {
+        return { ok: false, reason: 'invalid-root', message: `root is not an existing directory: ${args.root}` };
+      }
+      root = args.root;
+    } else {
+      const cwd = process.cwd();
+      if (!isRefusedWalkRoot(cwd) && cwdIsRepo(cwd)) {
+        root = cwd;
+      } else if (mode === 'all') {
+        root = cwd;
+      } else {
+        return {
+          ok: false,
+          reason: 'no-repo-root',
+          message: 'The Shakers MCP server is running from a non-repository directory, so there is no repository to evaluate. Pass an absolute path to the repository via `root`, or use repoScope.mode "all" for a machine-wide report.',
+        };
+      }
+    }
+
+    const consent = args.consent || {};
+    const granted = consent.granted === true;
+    const email = typeof consent.email === 'string' ? consent.email.trim() : '';
+
+    const verifySession = loadAuthSession();
+    const emailVerifiedByLogin =
+      sessionStatus(verifySession) === 'active'
+      && !!verifySession
+      && isValidEmail(verifySession.email);
+
+    if (granted) {
+      if (!isValidEmail(email)) {
+        throw new Error('consent.granted is true but consent.email is missing or invalid — ask the talent for their email.');
+      }
+      if (emailVerifiedByLogin) {
+        recordConsent('granted', verifySession.email, { verified: true });
+      } else {
+        recordConsent('granted', email, { verified: false });
+      }
+    } else {
+      recordConsent('denied');
+    }
+
+    const canSubmit = granted && emailVerifiedByLogin;
+    const submittedEmail = canSubmit ? verifySession.email : null;
+
+    const argv = buildArgv({ root, repoScope: args.repoScope, lang: args.lang });
+
+    let parsed;
+    const captured = await captureStdout(() => runAiUsage(argv));
+    parsed = parseReportJson(captured);
+    const { report, maturity } = parsed;
+
+    let savedLocally = false;
+    try {
+      persistFootprint({ root, report, maturity });
+      savedLocally = true;
+    } catch {
+      savedLocally = false;
+    }
+
+    const send = canSubmit
+      ? await autoShare(report, maturity, { root })
+      : { ok: false, skipped: true, reason: granted ? 'email-unverified' : 'consent-denied' };
+    const submitted = !!(send && send.ok);
+
+    const hasAgents = Array.isArray(report.agents) && report.agents.length > 0;
+
+    let enrichment = submitted && hasAgents ? 'pending' : 'none';
+    let enrichedAgents = null;
+    if (submitted && hasAgents) {
+      const session = loadAuthSession();
+      const endpoint = getUsageDiscoveredInventoryEndpoint();
+      if (sessionStatus(session) === 'active' && endpoint) {
+        const polled = await pollClassifiedInventory({
+          accessToken: session.accessToken,
+          endpoint,
+          requestDiscoveredInventory,
+          capMs: inlineWaitMs,
+        });
+        if (polled.status === 'ready') {
+          enrichment = 'ready';
+          enrichedAgents = polled.agents;
+        }
+      }
+    }
+
+    // "My work with AI" preview: only after a real submit this run.
+    let aiProfile = { status: 'unavailable', preview: null };
+    if (submitted) {
+      const usageSession = loadAuthSession();
+      if (sessionStatus(usageSession) === 'active') {
+        aiProfile = await resolveAiProfilePreview(
+          {
+            session: usageSession,
+            endpoint: getAiProfileEndpoint(),
+            timeoutMs: aiFluencyWaitMs,
+          },
+          {
+            refreshToken: async () => {
+              const fresh = await ensureFreshSession(process.env);
+              return fresh ? { accessToken: fresh.accessToken, hubAccessToken: fresh.hubAccessToken } : null;
+            },
+          },
+        );
+      }
+    }
+
+    const displayAgents = enrichedAgents
+      ? enrichedAgents.map((a) => ({ name: a.name, category: a.category, role: a.role }))
+      : (report.agents || []).map((a) => ({ name: a.name }));
+
+    // Same full report the CLI terminal prints, as plain markdown (no ANSI), so a chat client shows the talent the same thing.
+    const text = renderFullReportText(
+      report,
+      maturity,
+      { status: aiProfile.status, preview: aiProfile.preview },
+      { lang },
+    );
+
+    let message;
+    if (submitted) {
+      message =
+        enrichment === 'ready'
+          ? 'Classification complete — agent categories and descriptions are ready.'
+          : enrichment === 'pending'
+            ? 'Report submitted. Shakers is classifying the agents server-side (this is normal, not an error) — call ai_usage_result shortly to get their categories and descriptions.'
+            : 'Report submitted.';
+    } else if (send.reason === 'consent-denied') {
+      message = 'Not submitted — consent denied. The report was computed and saved locally only; nothing was sent to Shakers. Do not point the talent to "My work with AI".';
+    } else if (send.reason === 'email-unverified') {
+      message = "Not submitted — the talent's email is not verified. Ask them to log in / verify with the Shakers CLI (`shakers login`) first, then run ai_usage again; nothing was sent to Shakers.";
+    } else if (send.skipped) {
+      message = `Not submitted (${send.reason}). The report was computed and saved locally only; nothing was sent to Shakers.`;
+    } else {
+      message = `Submit failed (${send.reason}). The report was saved locally only; retry later.`;
+    }
+
+    return {
+      report,
+      maturity,
+      send,
+      savedLocally,
+      enrichment,
+      agents: enrichedAgents,
+      // Plain-text "My work with AI" report (no ANSI), same content/layout as the CLI.
+      text,
+      // "My work with AI" preview: status ready | pending | unavailable.
+      aiProfile,
+      next: submitted && enrichment === 'pending' ? 'ai_usage_result' : null,
+      message,
+      display: {
+        tier: {
+          key: maturity.tierKey,
+          name: maturity.tierName,
+          setupLevel: maturity.name,
+          score: maturity.score,
+        },
+        // Matrix (3x3) + vision (E) + howIWork (F) + traction; null until projected.
+        aiProfile: {
+          status: aiProfile.status,
+          setup: aiProfile.preview ? aiProfile.preview.matrix.setupCode : null,
+          usage: aiProfile.preview ? aiProfile.preview.matrix.usageLevel : null,
+          cell: aiProfile.preview ? aiProfile.preview.matrix.cell : null,
+          isAiNative: aiProfile.preview ? aiProfile.preview.matrix.isAiNative : false,
+          vision: aiProfile.preview ? aiProfile.preview.vision : null,
+          howIWork: aiProfile.preview ? aiProfile.preview.howIWork : null,
+          traction: aiProfile.preview ? aiProfile.preview.traction : null,
+        },
+        tierLegend: tierLadder(),
+        agents: displayAgents,
+      },
+      scope: {
+        mode: (args.repoScope && args.repoScope.mode) || 'current',
+        root,
+      },
+      consent: { granted, email: canSubmit ? submittedEmail : (granted ? email : null) },
+    };
+  }
+
+  return {
+    name: 'ai_usage',
+    description:
+      "Measure how a Shakers talent uses AI in their work: scans this machine and repository for AI-tool usage (subagents, MCP servers, sessions, git activity), scores their AI-maturity tier (T0-T7), and, with the talent's consent, submits the report to Shakers so their profile reflects it. Runs entirely on the talent's own machine. Ask the talent for consent and their email in the chat before calling. Submission also requires an active, email-verified Shakers session (via `shakers login` / registration OTP): with consent denied OR no verified session the report is computed and saved locally only and nothing is sent — check the `send` field for the outcome. Always fast and deterministic: it runs no LLM locally. Agent descriptions and catalog classification are produced by Shakers server-side. This waits briefly (~30s) and, if classification finishes, returns the enriched agents inline; otherwise it returns enrichment:'pending' (normal progress, not an error) and you should call `ai_usage_result` to get them. The `text` field is a ready-to-show plain-text 'My work with AI' report (Markdown, no ANSI) mirroring the CLI terminal — render it verbatim to the talent; the matrix grid is inside a fenced code block, keep it fenced so it stays aligned. Use the `display` block for structured access: show the tier (with the tierLegend explaining T0-T7) and the agent list by NAME and category/role. IDs and codes (agent `code`, skillId, catalogId) are internal handles for the add_* tools only — never show raw IDs or codes to the talent.",
+    inputSchema: AI_USAGE_INPUT_SCHEMA,
+    handler,
+  };
+}
+
+module.exports = {
+  makeAiUsageTool,
+  AI_USAGE_INPUT_SCHEMA,
+  buildArgv,
+  parseReportJson,
+  defaultCaptureStdout,
+};

package/src/mcp-alma-tools.js

@@ -0,0 +1,91 @@
+'use strict';
+
+const ALMA_CHAT_SCHEMA = {
+  type: 'object',
+  properties: {
+    message: { type: 'string', description: 'The message for Alma.' },
+  },
+  required: ['message'],
+};
+
+const ALMA_DECISION_SCHEMA = {
+  type: 'object',
+  properties: {
+    approved: { type: 'boolean', description: "The talent's decision on the pending confirmation: true = go ahead, false = cancel." },
+  },
+  required: ['approved'],
+};
+
+function makeAlmaTools(deps = {}) {
+  const {
+    askAlma = (opts) => require('./alma-client').askAlma({}, opts),
+    decideAlma = (opts) => require('./alma-client').decideAlma({}, opts),
+    loadAuthSession = require('./auth-session-store').loadAuthSession,
+    sessionStatus = require('./auth-session-store').sessionStatus,
+  } = 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 (alma is session-gated).');
+    }
+    return session;
+  };
+
+  const captureEvents = () => {
+    let pending = null;
+    const links = [];
+    const onEvent = (evt) => {
+      if (!evt) return;
+      if (evt.type === 'confirmation_required') {
+        pending = { text: evt.text || '', irreversible: !!(evt.detail && String(evt.detail).length) };
+      } else if (evt.type === 'link' && evt.data && evt.data.to) {
+        links.push(String(evt.data.to));
+      }
+    };
+    return { onEvent, snapshot: () => ({ pending, links }) };
+  };
+
+  const relay = (res, cap) => {
+    if (!res.ok) return { ok: false, reason: res.reason };
+    const { pending, links } = cap.snapshot();
+    const out = { ok: true, answer: res.text };
+    if (pending) out.pendingConfirmation = pending;
+    if (links.length) out.webLinks = links;
+    return out;
+  };
+
+  async function almaChat(args = {}) {
+    const session = requireSession();
+    const message = typeof args.message === 'string' ? args.message.trim() : '';
+    if (!message) return { ok: false, reason: 'no-message' };
+    const cap = captureEvents();
+    const res = await askAlma({ hubAccessToken: session.hubAccessToken, message, onEvent: cap.onEvent });
+    return relay(res, cap);
+  }
+
+  async function almaDecision(args = {}) {
+    const session = requireSession();
+    if (typeof args.approved !== 'boolean') return { ok: false, reason: 'no-decision' };
+    const cap = captureEvents();
+    const res = await decideAlma({ hubAccessToken: session.hubAccessToken, approved: args.approved, onEvent: cap.onEvent });
+    return relay(res, cap);
+  }
+
+  return [
+    {
+      name: 'alma_chat',
+      description: "Send a message to Alma, the Shakers AI assistant, and get her answer (about the talent's profile, rate, availability, skills, positions, applications). Continuity is automatic across turns (same session). When Alma proposes a profile change she returns `pendingConfirmation { text, irreversible }` — DO NOT auto-approve: show the talent `pendingConfirmation.text` (and warn when irreversible), ask them yes/no, then call `alma_decision` with their answer. `webLinks` are web-only navigation targets. Relay the answer as-is; never show internal Shakers ids/codes.",
+      inputSchema: ALMA_CHAT_SCHEMA,
+      handler: almaChat,
+    },
+    {
+      name: 'alma_decision',
+      description: "Relay the talent's decision on the pending Alma action from alma_chat: approved=true makes Alma perform the change, approved=false cancels it. Call this ONLY after the talent has explicitly answered yes/no to the pendingConfirmation — never decide on their behalf.",
+      inputSchema: ALMA_DECISION_SCHEMA,
+      handler: almaDecision,
+    },
+  ];
+}
+
+module.exports = { makeAlmaTools, ALMA_CHAT_SCHEMA, ALMA_DECISION_SCHEMA };

package/src/mcp-applications-tools.js

@@ -0,0 +1,42 @@
+'use strict';
+
+// MCP: the positions the talent applied to + status.
+
+const LIST_APPLICATIONS_SCHEMA = { type: 'object', properties: {} };
+
+function makeApplicationsTools(deps = {}) {
+  const {
+    fetchApplications = (opts) => require('./applications-client').fetchApplications({}, 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_applications is session-gated).');
+    }
+    return session;
+  };
+
+  async function listApplications() {
+    const session = requireLoginSession();
+    const res = await fetchApplications({ hubAccessToken: session.hubAccessToken });
+    if (!res.ok) return { ok: false, reason: res.reason };
+    return { ok: true, applications: res.items || [] };
+  }
+
+  return [
+    {
+      name: 'list_applications',
+      description: "List the positions the talent has applied to, with each candidature's status. Read-only. Requires an active session. Any positionId/projectId in the result are INTERNAL handles for calling tools — never show or mention them to the talent; refer to a project by its title/company.",
+      inputSchema: LIST_APPLICATIONS_SCHEMA,
+      handler: listApplications,
+    },
+  ];
+}
+
+module.exports = {
+  makeApplicationsTools,
+  LIST_APPLICATIONS_SCHEMA,
+};

package/src/mcp-ask-tools.js

@@ -0,0 +1,50 @@
+'use strict';
+
+// MCP: ask Alma. Returns the AGGREGATED answer (MCP does not stream).
+
+const ASK_SCHEMA = {
+  type: 'object',
+  properties: {
+    message: { type: 'string', description: 'The question / message for Alma.' },
+  },
+  required: ['message'],
+};
+
+function makeAskTools(deps = {}) {
+  const {
+    askAlma = (opts) => require('./alma-client').askAlma({}, 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 (ask is session-gated).');
+    }
+    return session;
+  };
+
+  async function ask(args = {}) {
+    const session = requireLoginSession();
+    const message = typeof args.message === 'string' ? args.message.trim() : '';
+    if (!message) return { ok: false, reason: 'no-message' };
+    const res = await askAlma({ hubAccessToken: session.hubAccessToken, message });
+    if (!res.ok) return { ok: false, reason: res.reason };
+    return { ok: true, answer: res.text };
+  }
+
+  return [
+    {
+      name: 'ask',
+      description: 'Ask Alma, the Shakers AI assistant, a question (about your profile, rates, availability, skills, open positions, applications). Returns Alma\'s full answer — relay it as-is; do not surface any internal Shakers ids/codes to the talent.',
+      inputSchema: ASK_SCHEMA,
+      handler: ask,
+    },
+  ];
+}
+
+module.exports = {
+  makeAskTools,
+  ASK_SCHEMA,
+};