shakers-cli 0.0.0-stage → 0.14.1

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

@@ -0,0 +1,401 @@
+'use strict';
+
+const fs = require('fs');
+const { execFileSync } = require('child_process');
+const { isRefusedWalkRoot } = require('./scan-exclusions');
+const { askChoice, chatChoice, queueNotice } = require('./mcp-choice');
+
+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:
+        "The talent's explicit answer to the AI-usage question this tool asks together with both disclaimers. Nothing is scanned without granted:true. A yes to anything else is not this answer.",
+      properties: {
+        granted: { type: 'boolean', description: 'true ONLY after the talent explicitly said yes to the AI-usage question; false when they said no. Omit it to get the disclaimers and the question to ask.' },
+        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.' },
+  },
+};
+
+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 {
+    scanUsage = (argv) => require('../bin/ai-usage').scanUsage(argv),
+    autoShare = require('./share').autoShare,
+    recordConsent = require('./share').recordConsent,
+    isValidEmail = require('./share').isValidEmail,
+    persistFootprint = require('./report-store').persistFootprint,
+    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,
+    signupPhase = () => require('./mcp-signup-tools').signupPhase(),
+    usageDisclaimers = (lang) => require('./onboarding-flow').usageDisclaimers(lang),
+    signupCopy = require('./signup-copy').signupCopy,
+    signupLanguage = require('./signup-language').signupLanguage,
+  } = deps;
+
+  // The sign-up's one scan: started on the talent's yes once the account exists, uploaded in the background.
+  let job = null;
+  // The talent's answer in the consent dialog, so a later call cannot contradict it.
+  let dialogConsent = null;
+
+  function startSignupScan(argv, root) {
+    if (job) return job;
+    job = { state: 'scanning', send: null, uploading: null };
+    // performScan is synchronous: start it after this answer has gone out.
+    job.scan = new Promise((resolve) => { setImmediate(resolve); }).then(() => scanUsage(argv)).then((scan) => {
+      try { persistFootprint({ root, report: scan.report, maturity: scan.maturity }); } catch { /* local copy is best-effort */ }
+      return scan;
+    });
+    job.scan.catch(() => { job.state = 'failed'; });
+    job.root = root;
+    return job;
+  }
+
+  function uploadSignupScan() {
+    if (!job) return Promise.resolve(null);
+    if (job.uploading) return job.uploading;
+    const current = job;
+    current.uploading = current.scan.then(async (scan) => {
+      const session = loadAuthSession();
+      if (sessionStatus(session) !== 'active' || !session || !isValidEmail(session.email)) {
+        current.uploading = null;
+        return { ok: false, skipped: true, reason: 'no-session' };
+      }
+      current.state = 'uploading';
+      // Nobody awaits this promise: a local write error must end as a failed send, never as an
+      // unhandled rejection that takes the MCP process down.
+      let send;
+      try {
+        recordConsent('granted', session.email, { verified: true });
+        send = await autoShare(scan.report, scan.maturity, { root: current.root, bypassThrottle: true });
+      } catch (error) {
+        send = { ok: false, reason: 'upload-failed', message: error && error.message ? error.message : String(error) };
+      }
+      current.state = send && send.ok ? 'sent' : 'failed';
+      current.send = send;
+      return send;
+    }, () => ({ ok: false, skipped: true, reason: 'scan-failed' }));
+    return current.uploading;
+  }
+  function declined(lang) {
+    recordConsent('denied');
+    if (signupPhase() === 'account') {
+      queueNotice(signupCopy(lang).aiUsageSkipped);
+      return { ok: false, reason: 'consent-declined', message: 'Nothing was scanned. Say nothing about it: its fixed line for the talent comes with the next question. Carry on with the interview offer.' };
+    }
+    return { ok: false, reason: 'consent-declined', relayVerbatim: signupCopy(lang).aiUsageSkipped, message: 'Nothing was scanned. Show relayVerbatim once, word for word.' };
+  }
+
+  async function askConsent(lang, ctx) {
+    const c = signupCopy(lang);
+    const texts = Object.values(usageDisclaimers(lang));
+    const asked = ctx && ctx.elicitation
+      ? await askChoice(ctx, { texts, question: c.aiUsageQuestion, options: [c.aiUsageYes, c.aiUsageSkip] })
+      : { chat: chatChoice(c.aiUsageQuestion, [c.aiUsageYes, c.aiUsageSkip], texts) };
+    if (asked.answer === c.aiUsageSkip) {
+      dialogConsent = 'denied';
+      return declined(lang);
+    }
+    if (asked.answer === c.aiUsageYes) {
+      dialogConsent = 'granted';
+      return { ok: true, reason: 'consent-granted', consent: { granted: true }, message: 'The talent said yes in the dialog: do not ask again. Call ai_usage with consent.granted:true (and their email) to run it.' };
+    }
+    return {
+      ok: false,
+      reason: 'consent-required',
+      ...(asked.dismissed ? { dismissed: asked.dismissed } : {}),
+      ...asked.chat,
+      message: `Nothing was scanned. ${asked.chat.choiceMessage} Then call ai_usage again with consent.granted:true only after they pick the first option, or consent.granted:false if they skip it.`,
+    };
+  }
+
+  async function handler(args = {}, ctx = {}) {
+    const phase = signupPhase();
+    // The sign-up looks at the whole machine: the server rarely runs inside a repository there.
+    const repoScope = args.repoScope || (phase === 'account' ? { mode: 'all' } : undefined);
+    const mode = (repoScope && repoScope.mode) || 'current';
+    const lang = args.lang === 'es' || args.lang === 'en' ? args.lang : detectFlowLang();
+    const textLang = signupLanguage(lang);
+    if (phase === 'waiting') {
+      return { ok: false, reason: 'account-pending', message: 'Nothing was scanned. Ask about AI usage only once signup_status says the account exists.' };
+    }
+    const consent = args.consent || {};
+    if (consent.granted === false) return declined(textLang);
+    if (consent.granted === true && dialogConsent === 'denied') {
+      return { ok: false, reason: 'consent-declined', message: 'The talent skipped the AI-usage step in the dialog: nothing is scanned. Carry on without it. If they later ask for the scan themselves, call ai_usage without consent to ask them again.' };
+    }
+    if (consent.granted !== true) {
+      const answered = await askConsent(textLang, ctx);
+      // In the sign-up a yes in the dialog runs the scan right away, in the background.
+      if (!(answered.reason === 'consent-granted' && phase === 'account')) return answered;
+    }
+
+    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 email = typeof consent.email === 'string' ? consent.email.trim() : '';
+    const argv = buildArgv({ root, repoScope, lang: args.lang });
+
+    // In the sign-up the scan never holds the conversation: it runs and uploads in the background.
+    if (phase === 'account') {
+      const current = startSignupScan(argv, root);
+      uploadSignupScan();
+      return {
+        ok: true,
+        background: true,
+        send: current.send || { ok: false, skipped: true, reason: 'uploading' },
+        scope: { mode, root },
+        message: 'The analysis runs and uploads in the background; Shakers completes the profile with it in a few minutes. Do not wait for it and do not call ai_usage again: carry on with the interview offer.',
+      };
+    }
+
+    const verifySession = loadAuthSession();
+    const emailVerifiedByLogin =
+      sessionStatus(verifySession) === 'active'
+      && !!verifySession
+      && isValidEmail(verifySession.email);
+
+    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 });
+    }
+
+    const canSubmit = emailVerifiedByLogin;
+    const submittedEmail = canSubmit ? verifySession.email : null;
+
+    const { report, maturity } = await scanUsage(argv);
+
+    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: 'email-unverified' };
+    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 === '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 kept on this machine only; nothing was sent to Shakers.`;
+    } else {
+      message = `Submit failed (${send.reason}). The report was kept on this machine 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,
+        root,
+      },
+      consent: { granted: true, email: canSubmit ? submittedEmail : email },
+    };
+  }
+
+  return {
+    name: 'ai_usage',
+    title: 'Analyse how you work with AI',
+    description: 'Asks you first and, only if you say yes, looks at which AI tools you use on this computer and the history of your code projects. With your yes it sends a summary with anonymised excerpts to your Shakers profile; your code and prompts never leave your computer.',
+    guidance:
+      "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. Before any scan, call it without consent: it asks the AI-usage question with both disclaimers in the same block (a dialog, or `say` to print word for word); only an explicit yes allows consent.granted:true, and skipping is consent.granted:false. In the sign-up it is the step right after the account exists and before the interview: on yes it runs and uploads in the background, never wait for it. Submission also requires an active, email-verified Shakers session (via `shakers login` / registration OTP): without a verified session the report stays on this machine and nothing is sent — check the `send` field for the outcome. Always fast and deterministic: it runs no LLM on the machine. 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,
+};

package/src/mcp-alma-tools.js

@@ -0,0 +1,95 @@
+'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 — sign in with social_signin_start (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',
+      title: 'Chat with Alma',
+      description: 'Sends your message to Alma, the Shakers assistant, and shows her answer. If she proposes a change to your profile, you are asked before it is made.',
+      guidance: "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',
+      title: "Confirm Alma's change",
+      description: 'Sends your yes or no to a profile change Alma proposed.',
+      guidance: "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,44 @@
+'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 — sign in with social_signin_start (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',
+      title: 'Your applications',
+      description: 'Shows the projects you applied to and how each application is going.',
+      guidance: "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,
+};