shakers-cli-beta 0.8.0-beta.0

package/src/usage-model-calls.js

@@ -0,0 +1,119 @@
+'use strict';
+
+// The three ephemeral model-call orchestrators of the `ai-usage` flow, extracted from bin/ai-usage.js (structure refactor, issue 020).
+
+const { parseAgentDescriptions, parseAgentDefinitionsForRoots } = require('./agent-org-chart');
+const {
+  buildSynthesisRequest,
+  requestAgentSynthesis,
+  buildAgentEvaluationRequest,
+  requestAgentEvaluation,
+  buildRoadmapPersonalizationRequest,
+  requestRoadmapPersonalization,
+} = require('./ai');
+const { MODEL_CALL, REASON, skipped, failedLocally, attachModelCall } = require('./model-call-record');
+const {
+  getSynthesisEndpoint,
+  getRoadmapEndpoint,
+  getAgentEvaluationEndpoint,
+} = require('./config');
+const { hasTraceContentConsent } = require('./share');
+const { getRoadmapEntry } = require('./roadmap-content');
+const { computeTierResult } = require('./tier-engine');
+
+// Agent-synthesis call (talents-ai-score, ADR-010/ADR-011, "ephemeral" — not persisted; ADR-051 amends WHEN it runs, not that).
+async function maybeSynthesizeAgents(report, root) {
+  const KEY = MODEL_CALL.SYNTHESIS;
+  if (!Array.isArray(report.agents) || report.agents.length === 0) {
+    attachModelCall(report, KEY, skipped(REASON.NO_AGENTS));
+    return null;
+  }
+  const endpoint = getSynthesisEndpoint();
+  if (!endpoint) {
+    attachModelCall(report, KEY, skipped(REASON.NO_ENDPOINT));
+    return null;
+  }
+
+  try {
+    const descriptions = Array.isArray(report.agentDescriptions)
+      ? report.agentDescriptions
+      : parseAgentDescriptions(root);
+    const requestBody = buildSynthesisRequest(report.agents, descriptions, hasTraceContentConsent());
+    return await requestAgentSynthesis(requestBody, {
+      endpoint,
+      onOutcome: (rec) => attachModelCall(report, KEY, rec),
+    });
+  } catch {
+    // A failure BEFORE the wire (reading/parsing the agent files threw), which
+    // is a local defect and not the endpoint's fault — recorded as such.
+    attachModelCall(report, KEY, failedLocally());
+    return null; // never breaks the local report — falls back to the org chart
+  }
+}
+
+// Ephemeral agent-evaluation call (ADR-016): scores each agent's DEFINITION quality server-side (gemini-2.5-flash — see src/agent-evaluation.js).
+async function maybeEvaluateAgents(report, roots, lang) {
+  const KEY = MODEL_CALL.EVALUATION;
+  if (!Array.isArray(report.agents) || report.agents.length === 0) {
+    attachModelCall(report, KEY, skipped(REASON.NO_AGENTS));
+    return null;
+  }
+  const endpoint = getAgentEvaluationEndpoint();
+  if (!endpoint) {
+    attachModelCall(report, KEY, skipped(REASON.NO_ENDPOINT));
+    return null;
+  }
+
+  try {
+    const definitions = parseAgentDefinitionsForRoots(roots);
+    // ADR-026: pass the report language so the rationale + the one-line description come back translated (a Spanish-authored definition still yields report-language prose).
+    const requestBody = buildAgentEvaluationRequest(report.agents, definitions, lang, hasTraceContentConsent());
+    return await requestAgentEvaluation(requestBody, {
+      endpoint,
+      onOutcome: (rec) => attachModelCall(report, KEY, rec),
+    });
+  } catch {
+    attachModelCall(report, KEY, failedLocally());
+    return null; // never breaks the local report
+  }
+}
+
+async function maybePersonalizeRoadmap(report, maturity, lang) {
+  const KEY = MODEL_CALL.ROADMAP;
+  const tierKey = maturity && maturity.tierKey;
+  if (!tierKey) {
+    attachModelCall(report, KEY, skipped(REASON.NOT_APPLICABLE));
+    return null;
+  }
+  const entry = getRoadmapEntry(tierKey, lang);
+  if (!entry) {
+    attachModelCall(report, KEY, skipped(REASON.NOT_APPLICABLE));
+    return null;
+  }
+  if (entry.maxTier) {
+    attachModelCall(report, KEY, skipped(REASON.MAX_TIER));
+    return null;
+  }
+
+  const endpoint = getRoadmapEndpoint();
+  if (!endpoint) {
+    attachModelCall(report, KEY, skipped(REASON.NO_ENDPOINT));
+    return null;
+  }
+
+  try {
+    const tierResult = computeTierResult(report);
+    // ADR-026: pass the report language so the personalized prose is localized.
+    // ADR-028: fresh consent read, see maybeSynthesizeAgents above.
+    const requestBody = buildRoadmapPersonalizationRequest(entry, tierResult, report, lang, hasTraceContentConsent());
+    return await requestRoadmapPersonalization(requestBody, {
+      endpoint,
+      onOutcome: (rec) => attachModelCall(report, KEY, rec),
+    });
+  } catch {
+    attachModelCall(report, KEY, failedLocally());
+    return null; // never breaks the local report — falls back to the curated content
+  }
+}
+
+module.exports = { maybeSynthesizeAgents, maybeEvaluateAgents, maybePersonalizeRoadmap };

package/src/usage-oneshot-commands.js

@@ -0,0 +1,180 @@
+'use strict';
+
+// One-shot command handlers extracted from bin/ai-usage.js (structure refactor, issue 020).
+
+const {
+  getConsentStatus,
+  revokeConsent,
+  resetConsent,
+  setEmail,
+} = require('./share');
+const { createStdinAsk } = require('./stdin-ask');
+const {
+  setIngestEndpoint,
+  resolveIngestEndpoint,
+  hasRetiredFallbackConfig,
+  isTalentProfile,
+} = require('./config');
+const { buildNextLevelStarter } = require('./build-next-level');
+
+// One-shot consent management commands (issue 007). Mirror the retired
+// `--enroll` pattern: they act immediately and do NOT scan.
+
+function doConsentStatus(catalog) {
+  const status = getConsentStatus();
+  const s = catalog.consent.status;
+  process.stdout.write(`\n  ${s.heading}\n\n`);
+  const decisionLine =
+    status.consent === 'granted' ? s.decisionGranted
+    : status.consent === 'denied' ? s.decisionDenied
+    : s.decisionNone;
+  process.stdout.write(`  ${decisionLine}\n`);
+  process.stdout.write(`  ${s.email(status.email)}\n`);
+  if (status.consent === 'granted' && status.email && !status.emailVerified) {
+    process.stdout.write(`  ${isTalentProfile() ? s.verificationPending : s.emailUnverifiedExternal}\n`);
+  }
+  process.stdout.write(`  ${s.lastSentAt(status.lastSentAt)}\n\n`);
+}
+
+function doConsentRevoke(catalog) {
+  revokeConsent();
+  process.stdout.write(`\n  ${catalog.consent.revoked}\n\n`);
+}
+
+// skill-code-certification / ADR-003: clears the decision back to "no decision yet" so the consent question is asked again next run — distinct from revoke (which persists `denied`).
+function doConsentReset(catalog) {
+  resetConsent();
+  process.stdout.write(`\n  ${catalog.consent.reset}\n\n`);
+}
+
+function doConsentEmail(newEmail, catalog) {
+  const r = setEmail(newEmail);
+  if (r.ok) {
+    process.stdout.write(`\n  ${catalog.consent.emailChanged(r.state.email)}\n\n`);
+  } else {
+    process.stdout.write(`\n  ${catalog.consent.emailInvalidCli}\n\n`);
+    process.exitCode = 1;
+  }
+}
+
+async function confirmEndpointHost(host, ask, catalog) {
+  const e = catalog.endpoint;
+  const answer = await ask(e.confirmHostPrompt(host));
+  return String(answer || '').trim() === host;
+}
+
+// Endpoint config (endpoint-config task): one-shot, don't scan.
+async function doSetEndpoint(url, catalog, ask) {
+  const e = catalog.endpoint;
+  let r = setIngestEndpoint(url);
+  if (!r.ok && r.reason === 'needs-confirmation') {
+    const confirmed = await confirmEndpointHost(r.host, ask, catalog);
+    if (!confirmed) {
+      process.stdout.write(`\n  ${e.confirmHostMismatch}\n\n`);
+      process.exitCode = 1;
+      return;
+    }
+    r = setIngestEndpoint(url, process.env, { confirmed: true });
+  }
+  if (r.ok) {
+    process.stdout.write(`\n  ${e.setOk(r.value, r.path)}\n\n`);
+  } else {
+    const msg =
+      r.reason === 'insecure-remote' ? e.errInsecureRemote
+      : r.reason === 'invalid-url' || r.reason === 'bad-protocol' ? e.errInvalidUrl
+      : e.errEmpty;
+    process.stdout.write(`\n  ${msg}\n\n`);
+    process.exitCode = 1;
+  }
+}
+
+// Print the effective ingest endpoint(s) and where each resolved from (env var > config file > none), so a Talent can see what's configured without editing or exporting anything.
+function doShowEndpoint(catalog) {
+  const e = catalog.endpoint;
+  const r = resolveIngestEndpoint();
+  if (r.source === 'env') {
+    process.stdout.write(`\n  ${e.showEnv(r.endpoint)}\n\n`);
+  } else if (r.source === 'config-file') {
+    process.stdout.write(`\n  ${e.showConfigFile(r.endpoint, r.path)}\n\n`);
+  } else if (r.source === 'config-file-invalid') {
+    process.stdout.write(`\n  ${e.showConfigInvalid(r.path)}\n\n`);
+  } else {
+    process.stdout.write(`\n  ${e.showNone}\n\n`);
+  }
+
+  // ADR-042: there is no second hop any more.
+  if (hasRetiredFallbackConfig()) {
+    process.stdout.write(`  ${e.showFallbackRetired}\n\n`);
+  }
+
+}
+
+// "Construir el siguiente nivel ahora" (issue 021): optional, explicit phase — never runs unless the talent asks for it via --build-next-level.
+function doBuildNextLevel(root, maturity, force, catalog) {
+  const b = catalog.buildNextLevel;
+  const result = buildNextLevelStarter(root || process.cwd(), maturity.tierKey, { force });
+
+  if (!result.ok) {
+    const message =
+      result.reason === 'max-tier' ? b.maxTier
+      : result.reason === 'no-file-target' ? b.noFileTarget
+      : b.unrecognizedTier;
+    process.stdout.write(`\n  ${message}\n\n`);
+    return;
+  }
+
+  process.stdout.write(`\n  ${b.heading(result.targetTierKey)}\n`);
+  for (const f of result.files) {
+    const line =
+      f.status === 'created' ? b.created(f.filename)
+      : f.status === 'overwritten' ? b.overwritten(f.filename)
+      : b.skippedExists(f.filename);
+    process.stdout.write(`    ${line}\n`);
+  }
+  process.stdout.write('\n');
+}
+
+// The one-shot dispatch that used to sit at the top of `run()`: each command acts immediately and returns, without scanning.
+async function handleOneShotCommand({ opts, catalog, injectedAsk }) {
+  if (opts.consentStatus) {
+    doConsentStatus(catalog);
+    return true;
+  }
+  if (opts.consentRevoke) {
+    doConsentRevoke(catalog);
+    return true;
+  }
+  if (opts.consentReset) {
+    doConsentReset(catalog);
+    return true;
+  }
+  if (opts.consentEmail) {
+    doConsentEmail(opts.consentEmail, catalog);
+    return true;
+  }
+  if (opts.setEndpoint !== null) {
+    const ask = injectedAsk || createStdinAsk();
+    try {
+      await doSetEndpoint(opts.setEndpoint, catalog, ask);
+    } finally {
+      if (!injectedAsk) ask.close();
+    }
+    return true;
+  }
+  if (opts.showEndpoint) {
+    doShowEndpoint(catalog);
+    return true;
+  }
+  return false;
+}
+
+module.exports = {
+  handleOneShotCommand,
+  doConsentStatus,
+  doConsentRevoke,
+  doConsentReset,
+  doConsentEmail,
+  doSetEndpoint,
+  doShowEndpoint,
+  doBuildNextLevel,
+};

package/src/usage-repo-scope.js

@@ -0,0 +1,162 @@
+'use strict';
+
+// Repo-scoping for the `ai-usage` command, extracted from bin/ai-usage.js (structure refactor, issue 020).
+
+const { isRefusedWalkRoot } = require('./scan-exclusions');
+const {
+  detectRepos,
+  repoIdentityForCwd,
+  matchReposByFlag,
+  scopeFromSelection,
+  indexOfCurrentRepo,
+} = require('./detect-repos');
+const { promptSelect } = require('./prompt-select');
+const { createStdinAsk } = require('./stdin-ask');
+
+const MAX_MACHINE_WIDE_REPOS = 5;
+const SCOPE_MACHINE = 'machine';
+const SCOPE_REPO = 'repo';
+
+function currentRepoToplevel(cwd, repoIdentityFn = repoIdentityForCwd) {
+  try {
+    return repoIdentityFn(cwd).toplevel || cwd;
+  } catch {
+    return cwd;
+  }
+}
+
+// The real git toplevel of `cwd`, or null when `cwd` is not a repo (or is a refused system root like `/`, the MCP `cwd=/` case).
+function cwdRepoToplevel(cwd, repoIdentityFn = repoIdentityForCwd) {
+  if (isRefusedWalkRoot(cwd)) return null;
+  try {
+    return repoIdentityFn(cwd).toplevel || null;
+  } catch {
+    return null;
+  }
+}
+
+// Pure: builds the machine-wide root set.
+function machineWideToplevels(cwdRepoTop, detectedRepos, cap = MAX_MACHINE_WIDE_REPOS) {
+  const ordered = [];
+  const seen = new Set();
+  const push = (t) => {
+    if (typeof t !== 'string' || !t) return;
+    if (isRefusedWalkRoot(t)) return;
+    if (seen.has(t)) return;
+    seen.add(t);
+    ordered.push(t);
+  };
+  push(cwdRepoTop);
+  for (const r of detectedRepos || []) push(r && r.toplevel);
+  const capped = ordered.slice(0, cap);
+  return { toplevels: capped, total: ordered.length, capped: ordered.length > capped.length };
+}
+
+function cwdOnlyScope(repos, cwdToplevel) {
+  const idx = indexOfCurrentRepo(repos, cwdToplevel);
+  if (idx === -1) {
+    return { selectedCwds: new Set(), toplevels: [cwdToplevel], mode: 'cwd' };
+  }
+  const { selectedCwds, selectedToplevels } = scopeFromSelection(repos, [idx]);
+  return {
+    selectedCwds,
+    toplevels: selectedToplevels.length ? selectedToplevels : [cwdToplevel],
+    mode: 'cwd',
+  };
+}
+
+async function promptScope({ catalog, stdinIsTTY = true, mkAsk = createStdinAsk } = {}) {
+  const c = (catalog && catalog.cli) || {};
+  const items = [
+    { key: SCOPE_MACHINE, label: c.reposScopeOptionMachine || 'Whole machine' },
+    { key: SCOPE_REPO, label: c.reposScopeOptionRepo || 'Current repo' },
+  ];
+  const ask = mkAsk();
+  try {
+    const picked = await promptSelect({
+      ask,
+      stdinIsTTY,
+      out: (s) => process.stdout.write(`${s}\n`),
+      items,
+      labelFor: (it) => it.label,
+      header: c.reposScopePromptHeader || '',
+      hint: c.reposScopePromptHint || '',
+    });
+    return picked ? picked.key : null;
+  } finally {
+    if (ask && typeof ask.close === 'function') ask.close();
+  }
+}
+
+// Resolve which repos feed the AI-usage evaluation.
+async function resolveRepoScope({
+  opts,
+  cwd,
+  injectedAsk,
+  catalog,
+  detectReposFn = detectRepos,
+  repoIdentityFn = repoIdentityForCwd,
+  chooseScope = promptScope,
+  isTTY = !!process.stdin.isTTY && !!process.stdout.isTTY,
+}) {
+  const cwdToplevel = currentRepoToplevel(cwd, repoIdentityFn);
+  const cwdRepoTop = cwdRepoToplevel(cwd, repoIdentityFn);
+  const note = (s) => {
+    if (!opts.json) process.stdout.write(`\n  ${s}\n`);
+  };
+
+  const detect = () => {
+    try {
+      return detectReposFn(process.env);
+    } catch {
+      return { repos: [], unassignedSessionCount: 0 };
+    }
+  };
+
+  // 1. Explicit repo list always wins.
+  if (opts.repos) {
+    const { repos, unassignedSessionCount } = detect();
+    note(catalog.cli.reposDetectedNote(repos.length, unassignedSessionCount));
+    const { indices, unmatched } = matchReposByFlag(repos, opts.repos);
+    if (unmatched.length > 0) {
+      process.stderr.write(`  ${catalog.cli.reposFlagUnmatched(unmatched.join(', '))}\n`);
+    }
+    if (indices.length > 0) {
+      const { selectedCwds, selectedToplevels } = scopeFromSelection(repos, indices);
+      return { selectedCwds, toplevels: [...new Set(selectedToplevels)], mode: 'flag' };
+    }
+    return cwdOnlyScope(repos, cwdToplevel);
+  }
+
+  const wantsMachine = opts.allRepos || opts.machine || opts.scope === SCOPE_MACHINE;
+  const wantsRepo = opts.repo || opts.scope === SCOPE_REPO;
+
+  let choice = null;
+  if (wantsMachine) choice = SCOPE_MACHINE;
+  else if (wantsRepo) choice = SCOPE_REPO;
+  else if (isTTY && !injectedAsk && !opts.json) {
+    choice = await chooseScope({ catalog, stdinIsTTY: true });
+  }
+  if (choice === null) choice = SCOPE_REPO;
+
+  if (choice === SCOPE_MACHINE) {
+    const { repos, unassignedSessionCount } = detect();
+    note(catalog.cli.reposDetectedNote(repos.length, unassignedSessionCount));
+    const mw = machineWideToplevels(cwdRepoTop, repos);
+    if (mw.capped) {
+      process.stderr.write(`\n  ${catalog.cli.reposScopeCapped(mw.toplevels.length, mw.total)}\n`);
+    }
+    note(catalog.cli.reposScopeAll);
+    return {
+      selectedCwds: null,
+      toplevels: mw.toplevels.length ? mw.toplevels : [cwdToplevel],
+      mode: 'all',
+    };
+  }
+
+  // Current repo.
+  const { repos } = detect();
+  return cwdOnlyScope(repos, cwdToplevel);
+}
+
+module.exports = { resolveRepoScope, machineWideToplevels, promptScope };