shakers-cli 0.0.0-stage → 0.14.0

package/src/update-flow.js

@@ -0,0 +1,223 @@
+'use strict';
+
+const { execFileSync } = require('child_process');
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+
+// `update` is explicit and user-invoked (never a hot path), so these timeouts can be generous.
+const VIEW_TIMEOUT_MS = 20000;
+const INSTALL_TIMEOUT_MS = 180000;
+
+// Documented installer one-liner (README `curl | bash`, `release` branch); overridable for a non-default deployment.
+const DEFAULT_INSTALL_URL =
+  'https://raw.githubusercontent.com/devShakers/ai-usage-evaluator/release/install.sh';
+
+// Name/version/registry come from THIS package.json, so a renamed flavor adapts with no code change here.
+function readPackageInfo() {
+  try {
+    const pkg = require(path.join(__dirname, '..', 'package.json'));
+    const registry =
+      pkg.publishConfig && typeof pkg.publishConfig.registry === 'string'
+        ? pkg.publishConfig.registry
+        : null;
+    return {
+      name: typeof pkg.name === 'string' ? pkg.name : null,
+      version: typeof pkg.version === 'string' ? pkg.version : null,
+      registry,
+    };
+  } catch {
+    return { name: null, version: null, registry: null };
+  }
+}
+
+function realPathOrSelf(p) {
+  try {
+    return fs.realpathSync(p);
+  } catch {
+    return p;
+  }
+}
+
+// Root of the installed package = the parent of this src/ directory.
+function packageRoot() {
+  return realPathOrSelf(path.resolve(__dirname, '..'));
+}
+
+function npmGlobalRoot() {
+  try {
+    const out = execFileSync('npm', ['root', '-g'], {
+      encoding: 'utf8',
+      timeout: VIEW_TIMEOUT_MS,
+      stdio: ['ignore', 'pipe', 'ignore'],
+    });
+    return out ? realPathOrSelf(out.trim()) : null;
+  } catch {
+    return null;
+  }
+}
+
+// Detects how this CLI was installed (prefix | npm-global | npm-local | source | unknown) so the update lands where the CLI lives.
+function detectInstall(env = process.env) {
+  const root = packageRoot();
+  const nodeModulesSeg = `${path.sep}node_modules${path.sep}`;
+
+  if (!root.includes(nodeModulesSeg)) {
+    const home = realPathOrSelf(
+      env.SHAKERS_CLI_HOME ||
+        env.AI_FOOTPRINT_HOME ||
+        path.join(os.homedir(), '.shakers'),
+    );
+    if (root === home) return { kind: 'prefix', root };
+    if (fs.existsSync(path.join(root, '.git'))) return { kind: 'source', root };
+    return { kind: 'unknown', root };
+  }
+
+  const info = readPackageInfo();
+  const gRoot = npmGlobalRoot();
+  const globalPkgPath =
+    gRoot && info.name
+      ? realPathOrSelf(path.join(gRoot, ...info.name.split('/')))
+      : null;
+  if (globalPkgPath && root === globalPkgPath) {
+    return { kind: 'npm-global', root, global: true, projectDir: null };
+  }
+  // `.../project/node_modules/<@scope/name>` → the project dir owning the local node_modules is `up` segments up.
+  const up = info.name && info.name.includes('/') ? 3 : 2;
+  const projectDir = path.resolve(root, ...Array(up).fill('..'));
+  return { kind: 'npm-local', root, global: false, projectDir };
+}
+
+function classifyError(error) {
+  const code = error && error.code;
+  const stderr =
+    (error && error.stderr && error.stderr.toString()) ||
+    (error && error.message) ||
+    '';
+  if (code === 'ENOENT') return 'npm-not-found';
+  if (code === 'ETIMEDOUT' || /ETIMEDOUT|timed out/i.test(stderr))
+    return 'timeout';
+  if (/EACCES|permission denied|EPERM/i.test(stderr)) return 'permission';
+  if (/ENOTFOUND|ECONNREFUSED|network|ECONNRESET|getaddrinfo/i.test(stderr))
+    return 'network';
+  if (/\b401\b|\b403\b|unauthorized|forbidden|authentication/i.test(stderr))
+    return 'auth';
+  if (/E404|not found/i.test(stderr)) return 'not-found';
+  return 'unknown';
+}
+
+// `npm view <name>@latest version` prints only the version string (last line).
+function fetchLatestVersion({ name, registry } = {}) {
+  if (!name) return { ok: false, reason: 'no-package-name' };
+  const args = ['view', `${name}@latest`, 'version'];
+  if (registry) args.push('--registry', registry);
+  try {
+    const out = execFileSync('npm', args, {
+      encoding: 'utf8',
+      timeout: VIEW_TIMEOUT_MS,
+      stdio: ['ignore', 'pipe', 'pipe'],
+    });
+    const version = (out || '')
+      .trim()
+      .split('\n')
+      .map((l) => l.trim())
+      .filter(Boolean)
+      .pop();
+    return version ? { ok: true, version } : { ok: false, reason: 'empty-response' };
+  } catch (error) {
+    return { ok: false, reason: classifyError(error) };
+  }
+}
+
+function parseSemver(v) {
+  const core = String(v).trim().replace(/^v/, '').split('-')[0].split('+')[0];
+  return core.split('.').map((n) => parseInt(n, 10) || 0);
+}
+
+// -1/0/1 on the semver core; prerelease suffixes ignored (fine for an "is a newer release available" check).
+function compareVersions(a, b) {
+  const pa = parseSemver(a);
+  const pb = parseSemver(b);
+  for (let i = 0; i < 3; i++) {
+    const x = pa[i] || 0;
+    const y = pb[i] || 0;
+    if (x !== y) return x < y ? -1 : 1;
+  }
+  return 0;
+}
+
+function manualCommand({ name, registry } = {}) {
+  if (!name) return 'npm install -g <package>@latest';
+  const reg = registry ? ` --registry ${registry}` : '';
+  return `npm install -g ${name}@latest${reg}`;
+}
+
+// Resolves the exact command this install model needs to pull `@latest`.
+function buildUpdatePlan(install, info, env = process.env) {
+  const { name, registry } = info;
+  if (!name) return null;
+  if (install.kind === 'npm-global') {
+    const args = ['install', '-g', `${name}@latest`];
+    if (registry) args.push('--registry', registry);
+    return { type: 'npm', cmd: 'npm', args, cwd: undefined, label: 'npm (global)' };
+  }
+  if (install.kind === 'npm-local') {
+    const args = ['install', `${name}@latest`];
+    if (registry) args.push('--registry', registry);
+    return {
+      type: 'npm',
+      cmd: 'npm',
+      args,
+      cwd: install.projectDir || undefined,
+      label: 'npm (local project)',
+    };
+  }
+  if (install.kind === 'prefix') {
+    const url = env.SHAKERS_CLI_INSTALL_URL || DEFAULT_INSTALL_URL;
+    return {
+      type: 'installer',
+      url,
+      label: 'installer (~/.shakers)',
+      command: `curl -fsSL "${url}" | bash`,
+    };
+  }
+  return null;
+}
+
+// Inherited stdio so the user sees npm's progress; the installer path keeps SHAKERS_CLI_HOME/BIN so a re-run lands in the same prefix.
+function runInstall(plan, env = process.env) {
+  if (!plan) return { ok: false, reason: 'no-plan' };
+  try {
+    if (plan.type === 'npm') {
+      execFileSync(plan.cmd, plan.args, {
+        stdio: 'inherit',
+        timeout: INSTALL_TIMEOUT_MS,
+        cwd: plan.cwd,
+        env,
+      });
+      return { ok: true };
+    }
+    if (plan.type === 'installer') {
+      execFileSync('bash', ['-c', plan.command], {
+        stdio: 'inherit',
+        timeout: INSTALL_TIMEOUT_MS,
+        env,
+      });
+      return { ok: true };
+    }
+    return { ok: false, reason: 'no-plan' };
+  } catch (error) {
+    return { ok: false, reason: classifyError(error) };
+  }
+}
+
+module.exports = {
+  readPackageInfo,
+  detectInstall,
+  fetchLatestVersion,
+  compareVersions,
+  buildUpdatePlan,
+  runInstall,
+  manualCommand,
+  DEFAULT_INSTALL_URL,
+};

package/src/update-notifier.js

@@ -0,0 +1,113 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const crypto = require('crypto');
+const { spawn } = require('child_process');
+const { getConfigDir } = require('./config-dir');
+const { getCatalog } = require('./i18n');
+const { compareVersions } = require('./update-flow');
+
+// Non-blocking update notifier: the hot path only reads the cache synchronously; a detached unref'd worker does the network check.
+const CHECK_INTERVAL_MS = 24 * 60 * 60 * 1000;
+
+function cacheFilePath(env = process.env) {
+  return path.join(getConfigDir(env), 'update-check.json');
+}
+
+// `{ lastCheck, latest }` or null. Never throws — a missing/corrupt cache is "no data".
+function readCache(env = process.env) {
+  try {
+    const parsed = JSON.parse(fs.readFileSync(cacheFilePath(env), 'utf8'));
+    if (!parsed || typeof parsed !== 'object') return null;
+    return parsed;
+  } catch {
+    return null;
+  }
+}
+
+// Written by the background worker (and nowhere else on the hot path). Best-effort, atomic + 0600 like every other home-dir write (temp-in-same-dir + fsync + rename).
+function writeCache(data, env = process.env) {
+  const target = cacheFilePath(env);
+  const dir = path.dirname(target);
+  const tmp = path.join(dir, `.update-check.${process.pid}.${crypto.randomBytes(6).toString('hex')}.tmp`);
+  let fd = null;
+  try {
+    fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
+    const payload = JSON.stringify({ lastCheck: data.lastCheck, latest: data.latest });
+    fd = fs.openSync(tmp, 'wx', 0o600);
+    fs.writeFileSync(fd, payload);
+    try { fs.fsyncSync(fd); } catch { /* e.g. EINVAL on some filesystems */ }
+    fs.closeSync(fd);
+    fd = null;
+    fs.renameSync(tmp, target);
+    return true;
+  } catch {
+    if (fd !== null) { try { fs.closeSync(fd); } catch { /* already closed */ } }
+    try { fs.unlinkSync(tmp); } catch { /* never existed */ }
+    return false;
+  }
+}
+
+// `stdoutIsTTY` is injectable for tests; defaults to the real tty bit so piped/redirected/mcp-stdio stdout stays quiet.
+function isSuppressed({
+  argv = [],
+  command = null,
+  env = process.env,
+  stdoutIsTTY = process.stdout.isTTY,
+} = {}) {
+  if (env.SHAKERS_CLI_NO_UPDATE_NOTIFIER === '1') return true;
+  if (env.CI && env.CI !== 'false' && env.CI !== '0') return true;
+  if (!stdoutIsTTY) return true;
+  if (Array.isArray(argv) && argv.includes('--json')) return true;
+  if (command === 'update') return true;
+  return false;
+}
+
+// Synchronous: prints to stderr when the cached latest beats the installed version, never polluting stdout. Returns the notice (or null).
+function maybeNotify({ currentVersion, lang, env = process.env, out = null } = {}) {
+  if (!currentVersion) return null;
+  const cache = readCache(env);
+  if (!cache || typeof cache.latest !== 'string' || !cache.latest) return null;
+  if (compareVersions(currentVersion, cache.latest) >= 0) return null;
+  const t = getCatalog(lang).cli.updateNotifier;
+  const write = out || ((s) => process.stderr.write(s));
+  write(`\n  ${t.available(currentVersion, cache.latest)}\n  ${t.howTo}\n\n`);
+  return t.available(currentVersion, cache.latest);
+}
+
+// Spawns the detached, unref'd worker to refresh the cache, but only when it is missing or older than CHECK_INTERVAL_MS. Failures swallowed.
+function triggerBackgroundCheck({ name, env = process.env } = {}) {
+  if (!name) return false;
+  const cache = readCache(env);
+  const now = Date.now();
+  if (
+    cache &&
+    typeof cache.lastCheck === 'number' &&
+    now - cache.lastCheck < CHECK_INTERVAL_MS
+  ) {
+    return false;
+  }
+  try {
+    const worker = path.join(__dirname, '..', 'bin', 'update-check-worker.js');
+    const child = spawn(process.execPath, [worker, name], {
+      detached: true,
+      stdio: 'ignore',
+    });
+    child.on('error', () => {});
+    child.unref();
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+module.exports = {
+  cacheFilePath,
+  readCache,
+  writeCache,
+  isSuppressed,
+  maybeNotify,
+  triggerBackgroundCheck,
+  CHECK_INTERVAL_MS,
+};

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,
+};