shakers-cli-beta 0.9.0 → 0.10.0

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

@@ -3,6 +3,7 @@
 const fs = require('fs');
 const { execFileSync } = require('child_process');
 const { isRefusedWalkRoot } = require('./scan-exclusions');
+const { askChoice } = require('./mcp-choice');
 
 function isExistingDir(p) {
   try {
@@ -30,13 +31,17 @@ const AI_USAGE_INPUT_SCHEMA = {
     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.',
+        "The talent's explicit answer to the AI-usage question, asked right after showing both disclaimers verbatim. Nothing is scanned without granted:true. A yes to anything else is not this answer.",
       properties: {
-        granted: { type: 'boolean', description: 'Whether the talent granted consent to send the report.' },
+        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'],
     },
+    disclaimersShown: {
+      type: 'boolean',
+      description: 'true only after you showed the talent both AI-usage disclaimers word for word, right before this call. Without consent, it then asks the AI-usage question in a dialog when the client has one.',
+    },
     repoScope: {
       type: 'object',
       description: 'Which repositories feed the evaluation. Defaults to the current repository only.',
@@ -61,36 +66,6 @@ const AI_USAGE_INPUT_SCHEMA = {
   },
 };
 
-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);
@@ -106,12 +81,11 @@ function buildArgv({ root, repoScope, lang }) {
 
 function makeAiUsageTool(deps = {}) {
   const {
-    runAiUsage = require('../bin/ai-usage').run,
+    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,
-    captureStdout = defaultCaptureStdout,
     cwdIsRepo = defaultCwdIsRepo,
     loadAuthSession = require('./auth-session-store').loadAuthSession,
     sessionStatus = require('./auth-session-store').sessionStatus,
@@ -128,11 +102,123 @@ function makeAiUsageTool(deps = {}) {
     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;
 
-  async function handler(args = {}) {
-    const mode = (args.repoScope && args.repoScope.mode) || 'current';
+  // 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 consentRequired(lang, ctx) {
+    const c = signupCopy(lang);
+    const disclaimers = Object.values(usageDisclaimers(lang));
+    if (ctx && ctx.elicitation) {
+      return {
+        ok: false,
+        reason: 'consent-required',
+        relayVerbatim: disclaimers,
+        message: 'Nothing was scanned. Show the talent each relayVerbatim text word for word, each as its own block, without labels or paraphrase; then call ai_usage again with disclaimersShown:true and no consent: it asks the question in a dialog.',
+      };
+    }
+    return {
+      ok: false,
+      reason: 'consent-required',
+      relayVerbatim: disclaimers,
+      question: c.aiUsageQuestion,
+      options: [c.aiUsageYes, c.aiUsageSkip],
+      message: 'Nothing was scanned. Show the talent each relayVerbatim text word for word, each as its own block, without labels or paraphrase, then `question` with its `options` (your native choice buttons if you have them, otherwise a short numbered list). Then call again with consent.granted:true only after they pick the first option, or consent.granted:false if they skip it.',
+    };
+  }
+
+  function declined(lang) {
+    recordConsent('denied');
+    return { ok: false, reason: 'consent-declined', relayVerbatim: signupCopy(lang).aiUsageSkipped, message: 'Nothing was scanned. Show relayVerbatim once, word for word, and carry on with the interview offer.' };
+  }
+
+  async function askConsent(lang, ctx) {
+    const c = signupCopy(lang);
+    const asked = await askChoice(ctx, { question: c.aiUsageQuestion, options: [c.aiUsageYes, c.aiUsageSkip] });
+    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. The disclaimers are already shown: do not repeat them. ${asked.chat.choiceMessage} Then call again with consent.granted:true only after an explicit yes, or consent.granted:false if they say no.`,
+    };
+  }
+
+  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) {
+      if (args.disclaimersShown !== true || !(ctx && ctx.elicitation)) return consentRequired(textLang, ctx);
+      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) {
@@ -155,9 +241,21 @@ function makeAiUsageTool(deps = {}) {
       }
     }
 
-    const consent = args.consent || {};
-    const granted = consent.granted === true;
     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 =
@@ -165,28 +263,19 @@ function makeAiUsageTool(deps = {}) {
       && !!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 });
-      }
+    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('denied');
+      recordConsent('granted', email, { verified: false });
     }
 
-    const canSubmit = granted && emailVerifiedByLogin;
+    const canSubmit = 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;
+    const { report, maturity } = await scanUsage(argv);
 
     let savedLocally = false;
     try {
@@ -198,7 +287,7 @@ function makeAiUsageTool(deps = {}) {
 
     const send = canSubmit
       ? await autoShare(report, maturity, { root })
-      : { ok: false, skipped: true, reason: granted ? 'email-unverified' : 'consent-denied' };
+      : { ok: false, skipped: true, reason: 'email-unverified' };
     const submitted = !!(send && send.ok);
 
     const hasAgents = Array.isArray(report.agents) && report.agents.length > 0;
@@ -263,14 +352,12 @@ function makeAiUsageTool(deps = {}) {
           : 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.`;
+      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 saved locally only; retry later.`;
+      message = `Submit failed (${send.reason}). The report was kept on this machine only; retry later.`;
     }
 
     return {
@@ -308,17 +395,17 @@ function makeAiUsageTool(deps = {}) {
         agents: displayAgents,
       },
       scope: {
-        mode: (args.repoScope && args.repoScope.mode) || 'current',
+        mode,
         root,
       },
-      consent: { granted, email: canSubmit ? submittedEmail : (granted ? email : null) },
+      consent: { granted: true, email: canSubmit ? submittedEmail : email },
     };
   }
 
   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.",
+      "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, show the talent both AI-usage disclaimers word for word, each as its own block, right before the AI-usage question (call without consent to get those texts and the question); 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,
   };
@@ -328,6 +415,4 @@ module.exports = {
   makeAiUsageTool,
   AI_USAGE_INPUT_SCHEMA,
   buildArgv,
-  parseReportJson,
-  defaultCaptureStdout,
 };