shakers-cli 0.0.0-stage → 0.14.1

package/src/certify-dimension-client.js

@@ -0,0 +1,163 @@
+'use strict';
+
+// Dimension-certification discovery + lifecycle client (hub + certs endpoints).
+
+const { postJsonWithTimeout } = require('./backend-request');
+const { reasonForError } = require('./onboarding-client');
+
+const DEFAULT_TIMEOUT_MS = 20000;
+
+function parseJson(raw) {
+  try {
+    return raw ? JSON.parse(raw) : null;
+  } catch {
+    return null;
+  }
+}
+
+function payloadOf(raw) {
+  const json = parseJson(raw);
+  if (!json || typeof json !== 'object') return undefined;
+  if (json.status === 'OK') return json.data;
+  return json;
+}
+
+function bearerHeaders(accessToken) {
+  const headers = {};
+  if (typeof accessToken === 'string' && accessToken) headers.Authorization = `Bearer ${accessToken}`;
+  return headers;
+}
+
+function pick(obj, keys) {
+  for (const k of keys) {
+    const v = obj && obj[k];
+    if (v !== undefined && v !== null && v !== '') return v;
+  }
+  return null;
+}
+
+// FLAG: hub gives `clusterId`, certs keys templates by `clusterRef`; assumed equal here.
+function composeDimensionKey(clusterRef, slug) {
+  if (!clusterRef || !slug) return null;
+  return `${clusterRef}/${slug}`;
+}
+
+async function requestMyCertifications({ hubAccessToken } = {}, { endpoint, timeoutMs = DEFAULT_TIMEOUT_MS } = {}) {
+  if (!endpoint) return { ok: false, reason: 'no-endpoint' };
+  if (!hubAccessToken) return { ok: false, reason: 'no-hub-token' };
+  let res;
+  try {
+    res = await postJsonWithTimeout(endpoint, null, timeoutMs, 'GET', null, bearerHeaders(hubAccessToken));
+  } catch (e) {
+    return { ok: false, reason: (e && e.kind) || 'network-error' };
+  }
+  if (res.status < 200 || res.status >= 300) return { ok: false, reason: reasonForError(res.status, res.raw) };
+
+  const data = payloadOf(res.raw);
+  if (data === undefined || !data || typeof data !== 'object') return { ok: false, reason: 'bad-response' };
+  const rawDims = Array.isArray(data) ? data
+    : (Array.isArray(data.dimensions) ? data.dimensions
+      : (Array.isArray(data.items) ? data.items : []));
+  const dimensions = rawDims
+    .map((d) => ({
+      slug: pick(d, ['slug', 'dimensionSlug', 'key']),
+      clusterId: pick(d, ['clusterRef', 'clusterId', 'clusterKey', 'cluster']),
+      state: pick(d, ['state', 'status']),
+      band: pick(d, ['band', 'level']) || null,
+    }))
+    .filter((d) => d.slug && d.clusterId);
+  return { ok: true, mainRole: pick(data, ['mainRole', 'role']) || null, dimensions };
+}
+
+// @Public: no auth header. Returns a Map dimensionKey -> deliveryFormat.
+async function requestTemplatesByDimension({ dimensionKeys } = {}, { endpoint, timeoutMs = DEFAULT_TIMEOUT_MS } = {}) {
+  if (!endpoint) return { ok: false, reason: 'no-endpoint' };
+  const keys = (Array.isArray(dimensionKeys) ? dimensionKeys : []).filter(Boolean);
+  if (keys.length === 0) return { ok: true, formats: new Map() };
+
+  const url = `${endpoint}${endpoint.includes('?') ? '&' : '?'}dimensionKeys=${keys.map(encodeURIComponent).join(',')}`;
+  let res;
+  try {
+    res = await postJsonWithTimeout(url, null, timeoutMs, 'GET', null, {});
+  } catch (e) {
+    return { ok: false, reason: (e && e.kind) || 'network-error' };
+  }
+  if (res.status < 200 || res.status >= 300) return { ok: false, reason: reasonForError(res.status, res.raw) };
+
+  const data = payloadOf(res.raw);
+  if (data === undefined || data === null) return { ok: false, reason: 'bad-response' };
+
+  // The real certs route returns rows under `data.items`; templates/bare-array are tolerant fallbacks.
+  const formats = new Map();
+  const rows = Array.isArray(data)
+    ? data
+    : (Array.isArray(data.items) ? data.items
+      : (Array.isArray(data.templates) ? data.templates : null));
+  if (rows) {
+    for (const t of rows) {
+      const key = pick(t, ['dimensionKey', 'key', 'dimension']);
+      const fmt = pick(t, ['deliveryFormat', 'delivery_format', 'format']);
+      if (key && fmt) formats.set(String(key), String(fmt));
+    }
+  } else if (typeof data === 'object') {
+    for (const [key, value] of Object.entries(data)) {
+      const fmt = value && typeof value === 'object' ? pick(value, ['deliveryFormat', 'delivery_format', 'format']) : value;
+      if (fmt) formats.set(String(key), String(fmt));
+    }
+  }
+  return { ok: true, formats };
+}
+
+// What the terminal can run: the templates marked for it, and the spoken ones, which are
+// conversation only. Whiteboard and screen share need the web.
+const TEXT_DELIVERY_FORMATS = new Set(['terminal', 'spoken_case']);
+
+function composeOfferableDimensions({ dimensions, formats } = {}) {
+  const fmt = formats instanceof Map ? formats : new Map(Object.entries(formats || {}));
+  const candidates = (Array.isArray(dimensions) ? dimensions : [])
+    .filter((d) => d && d.state !== 'CERTIFIED')
+    .map((d) => ({ ...d, dimensionKey: composeDimensionKey(d.clusterId, d.slug) }))
+    .filter((d) => d.dimensionKey);
+  const offerable = candidates.filter((d) => TEXT_DELIVERY_FORMATS.has(fmt.get(d.dimensionKey)));
+  const unmatched = candidates
+    .filter((d) => !fmt.has(d.dimensionKey))
+    .map((d) => d.dimensionKey);
+  return { offerable, unmatched };
+}
+
+async function discoverOfferableDimensions(deps = {}, { accessToken, hubAccessToken, timeoutMs = DEFAULT_TIMEOUT_MS } = {}) {
+  const {
+    getMyCertificationsEndpoint = require('./config').getMyCertificationsEndpoint,
+    getTemplatesByDimensionEndpoint = require('./config').getTemplatesByDimensionEndpoint,
+    requestMyCertifications: myCerts = requestMyCertifications,
+    requestTemplatesByDimension: templates = requestTemplatesByDimension,
+  } = deps;
+
+  const mineEndpoint = getMyCertificationsEndpoint();
+  if (!mineEndpoint) return { ok: false, reason: 'no-endpoint' };
+  const mine = await myCerts({ hubAccessToken }, { endpoint: mineEndpoint, timeoutMs });
+  if (!mine.ok) return { ok: false, reason: mine.reason };
+
+  const candidateDims = mine.dimensions.filter((d) => d.state !== 'CERTIFIED');
+  if (candidateDims.length === 0) return { ok: true, mainRole: mine.mainRole, offerable: [], unmatched: [] };
+
+  const templatesEndpoint = getTemplatesByDimensionEndpoint();
+  if (!templatesEndpoint) return { ok: false, reason: 'no-endpoint' };
+  const keys = candidateDims
+    .map((d) => composeDimensionKey(d.clusterId, d.slug))
+    .filter(Boolean);
+  const tmpl = await templates({ dimensionKeys: keys }, { endpoint: templatesEndpoint, timeoutMs });
+  if (!tmpl.ok) return { ok: false, reason: tmpl.reason };
+
+  const { offerable, unmatched } = composeOfferableDimensions({ dimensions: candidateDims, formats: tmpl.formats });
+  return { ok: true, mainRole: mine.mainRole, offerable, unmatched };
+}
+
+module.exports = {
+  requestMyCertifications,
+  requestTemplatesByDimension,
+  composeDimensionKey,
+  composeOfferableDimensions,
+  discoverOfferableDimensions,
+  TEXT_DELIVERY_FORMATS,
+};

package/src/certify-dimension-flow.js

@@ -0,0 +1,135 @@
+'use strict';
+
+// `certify` dimension flow: discover -> pick -> hand over the web deep link. The interview runs on the web.
+
+const { runInteractiveMultiSelect } = require('./interactive-select');
+
+function makeCertifyDimensionDeps(overrides = {}) {
+  const config = require('./config');
+  const client = require('./certify-dimension-client');
+  return {
+    getTalentProfileUrl: config.getTalentProfileUrl,
+    discoverOfferableDimensions: (opts) => client.discoverOfferableDimensions({}, opts),
+    buildWebLink,
+    ...overrides,
+  };
+}
+
+// The web route validates the decoded `dimension` param against `^[^/]+\/[^/]+$`,
+// so the separator slash stays literal and each segment is url-encoded.
+function buildWebLink(profileUrl, { clusterId, slug } = {}) {
+  if (!profileUrl || !clusterId || !slug) return null;
+  let origin;
+  try {
+    origin = new URL(profileUrl).origin;
+  } catch {
+    return null;
+  }
+  return `${origin}/certifications?dimension=${encodeURIComponent(clusterId)}/${encodeURIComponent(slug)}`;
+}
+
+// Numbered fallback when `ask` can't release stdin for raw mode.
+async function askNumberedChoice(ask, promptText, count) {
+  const raw = (await ask(promptText)).trim();
+  if (!raw) return null;
+  const n = Number.parseInt(raw, 10);
+  if (!Number.isInteger(n) || n < 1 || n > count) return null;
+  return n - 1;
+}
+
+async function chooseDimension(ask, stdinIsTTY, items, cd, out, { input, output } = {}) {
+  const labelFor = (d) => `${d.slug}${d.state === 'EXPIRED' ? ` (${cd.stateExpired})` : ''}`;
+  if (stdinIsTTY && typeof ask.suspend === 'function') {
+    ask.suspend();
+    const picked = await runInteractiveMultiSelect({
+      items,
+      labelFor,
+      header: cd.selectHeading,
+      hint: cd.selectHint,
+      single: true,
+      ...(input ? { input } : {}),
+      ...(output ? { output } : {}),
+    });
+    ask.resume();
+    return picked && picked.length ? picked[0] : null;
+  }
+  out(`\n  ${cd.selectHeading}\n`);
+  items.forEach((d, i) => out(`    ${i + 1}) ${labelFor(d)}\n`));
+  const idx = await askNumberedChoice(ask, `  ${cd.selectPrompt(items.length)}`, items.length);
+  return idx === null ? null : items[idx];
+}
+
+function resolveDimensionArg(arg, items) {
+  if (arg == null) return null;
+  const raw = String(arg).trim();
+  const n = Number.parseInt(raw, 10);
+  if (Number.isInteger(n) && String(n) === raw && n >= 1 && n <= items.length) return items[n - 1];
+  return items.find((d) => d.dimensionKey === raw || d.slug === raw) || undefined;
+}
+
+async function runCertifyDimension({ io, ask, stdinIsTTY, session, lang, catalog, opts = {}, deps = makeCertifyDimensionDeps() }) {
+  const cd = catalog.certifyDimension;
+  const accessToken = session ? session.accessToken : null;
+  const hubAccessToken = session ? session.hubAccessToken : null;
+
+  io.section(cd.title);
+
+  const discovered = await io.withProgress(cd.discovering, () =>
+    deps.discoverOfferableDimensions({ accessToken, hubAccessToken }));
+  if (!discovered.ok) {
+    io.error(cd.discoverFailed(discovered.reason));
+    return { ok: false, reason: discovered.reason, step: 'discover' };
+  }
+
+  if (Array.isArray(discovered.unmatched) && discovered.unmatched.length > 0) {
+    io.warn(cd.unmatchedNote(discovered.unmatched.join(', ')));
+  }
+
+  const offerable = Array.isArray(discovered.offerable) ? discovered.offerable : [];
+  if (offerable.length === 0) {
+    io.notify(cd.noneOfferable);
+    return { ok: true, none: true };
+  }
+  const mainRole = discovered.mainRole;
+  // The hub sends the main role as { clusterId, name, ... }.
+  const mainRoleName = mainRole && typeof mainRole === 'object' ? mainRole.name || mainRole.clusterId : mainRole;
+  if (mainRoleName) io.notify(cd.mainRole(mainRoleName));
+
+  let chosen;
+  if (opts.dimension != null) {
+    const resolved = resolveDimensionArg(opts.dimension, offerable);
+    if (!resolved) {
+      io.error(cd.dimensionInvalid);
+      return { ok: false, reason: 'bad-dimension', step: 'select' };
+    }
+    chosen = resolved;
+    io.notify(cd.dimensionUsing(chosen.slug));
+  } else if (!stdinIsTTY) {
+    io.error(cd.selectNonInteractive);
+    return { ok: false, reason: 'non-interactive', step: 'select' };
+  } else {
+    chosen = await chooseDimension(ask, stdinIsTTY, offerable, cd, (s) => io.notify(s.replace(/\n$/, '')), opts);
+    if (!chosen) {
+      io.notify(cd.selectNoneChosen);
+      return { ok: true, cancelled: true };
+    }
+  }
+
+  const link = deps.buildWebLink(deps.getTalentProfileUrl(), { clusterId: chosen.clusterId, slug: chosen.slug });
+  if (!link) {
+    io.warn(cd.webHandoffNoLink);
+    return { ok: true, handoff: null, dimension: chosen.dimensionKey };
+  }
+
+  io.notify(cd.webHandoff);
+  io.notify(cd.webHandoffLink(link));
+  return { ok: true, handoff: link, dimension: chosen.dimensionKey };
+}
+
+module.exports = {
+  makeCertifyDimensionDeps,
+  runCertifyDimension,
+  buildWebLink,
+  chooseDimension,
+  resolveDimensionArg,
+};

package/src/certify-disclaimer.js

@@ -0,0 +1,51 @@
+'use strict';
+
+// Legal disclaimer + EXPLICIT acceptance gate (ADR-001), shown before egress. Skill-code certify was retired (certify is now a dimension LiveKit interview); consumers today are the add-skill/add-agent/add-project consent gates.
+
+const { renderLegalNotice } = require('./legal-notice');
+const { styleQuestion } = require('./ansi');
+
+const MAX_ATTEMPTS = 5;
+const YES_RE = /^(y|yes|s|si|sí)$/i;
+const NO_RE = /^(n|no)$/i;
+
+function isAffirmative(raw) {
+  return YES_RE.test(String(raw).trim());
+}
+function isNegative(raw) {
+  return NO_RE.test(String(raw).trim());
+}
+
+async function confirmDisclaimerAcceptance({ ask, catalog, preAccepted = false, stdinIsTTY = true, text = null, drainBeforeAsk = false }) {
+  const d = catalog.certify;
+  const shown = text || d.disclaimer;
+
+  // The disclaimer TEXT is always shown, even when pre-accepting via flag — the talent (or the script author who chose the flag) still sees what they're accepting.
+  process.stdout.write(`\n  ${renderLegalNotice(shown, catalog)}\n`);
+
+  if (preAccepted) {
+    process.stdout.write(`  ${d.disclaimerAcceptedFlag}\n\n`);
+    return { accepted: true, reason: 'flag' };
+  }
+
+  if (!stdinIsTTY) {
+    process.stdout.write(`  ${d.disclaimerNonInteractive}\n\n`);
+    return { accepted: false, reason: 'non-interactive' };
+  }
+
+  if (drainBeforeAsk && typeof ask.drain === 'function') ask.drain();
+
+  for (let attempt = 0; attempt < MAX_ATTEMPTS; attempt++) {
+    const raw = String(await ask(styleQuestion(d.disclaimerQuestion))).trim();
+    if (isAffirmative(raw)) return { accepted: true, reason: 'interactive' };
+    if (isNegative(raw)) {
+      process.stdout.write(`  ${d.disclaimerDeclined}\n\n`);
+      return { accepted: false, reason: 'declined' };
+    }
+    process.stdout.write(`  ${d.disclaimerInvalidAnswer}\n`);
+  }
+  process.stdout.write(`  ${d.disclaimerNoAnswer}\n\n`);
+  return { accepted: false, reason: 'no-answer' };
+}
+
+module.exports = { confirmDisclaimerAcceptance, isAffirmative, isNegative };

package/src/certify-remediation-prompt.js

@@ -0,0 +1,23 @@
+'use strict';
+
+const { getCatalog } = require('./i18n');
+
+// Client-side "remediation prompt" for the certify report (skill-code- certification, issue 011).
+function buildRemediationPrompt(item, lang) {
+  const r = getCatalog(lang).certify.report;
+  const improvements =
+    item && item.result && Array.isArray(item.result.improvements)
+      ? item.result.improvements.filter((x) => typeof x === 'string' && x)
+      : [];
+  if (improvements.length === 0) return null;
+
+  const lines = [];
+  lines.push(r.remediationIntro(item.skillName, item.technology));
+  lines.push('');
+  improvements.forEach((imp, i) => lines.push(`${i + 1}. ${imp}`));
+  lines.push('');
+  lines.push(r.remediationClosing);
+  return lines.join('\n');
+}
+
+module.exports = { buildRemediationPrompt };

package/src/cli-args.js

@@ -0,0 +1,83 @@
+'use strict';
+
+const VALID_LANGS = new Set(['es', 'en']);
+const VALID_SCOPES = new Set(['machine', 'repo']);
+
+function parseScope(value) {
+  return VALID_SCOPES.has(value) ? value : null;
+}
+
+function parseRepoList(value) {
+  if (typeof value !== 'string') return null;
+  const items = value
+    .split(',')
+    .map((s) => s.trim())
+    .filter(Boolean);
+  return items.length > 0 ? items : null;
+}
+
+function parseArgs(argv) {
+  const opts = {
+    json: false,
+    save: true,
+    root: null,
+    help: false,
+    consentStatus: false,
+    consentRevoke: false,
+    consentReset: false,
+    consentEmail: null,
+    setEndpoint: null,
+    showEndpoint: false,
+    buildNextLevel: false,
+    force: false,
+    lang: null,
+    roadmap: false,
+    repos: null,
+    allRepos: false,
+    // Dynamic scope selector for the DEDICATED `ai-usage` command (a symptom fix: machine-wide runs were silently collapsing to the current repo's agents).
+    machine: false,
+    repo: false,
+    scope: null,
+    noAi: false,
+    // Issue 103: turns the section reveal off. Same name in both parsers, and the
+    // env var `NO_ANIMATION` does the same thing (the `NO_COLOR` pattern of 079).
+    noAnimation: false,
+  };
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === '--no-animation') opts.noAnimation = true;
+    else if (a === '--json') opts.json = true;
+    else if (a === '--no-save') opts.save = false;
+    else if (a === '--root') opts.root = argv[++i];
+    else if (a === '--consent-status') opts.consentStatus = true;
+    else if (a === '--consent-revoke') opts.consentRevoke = true;
+    else if (a === '--consent-reset') opts.consentReset = true;
+    else if (a === '--consent-email') opts.consentEmail = argv[++i];
+    else if (a.startsWith('--consent-email=')) opts.consentEmail = a.slice('--consent-email='.length);
+    else if (a === '--set-endpoint') opts.setEndpoint = argv[++i];
+    else if (a.startsWith('--set-endpoint=')) opts.setEndpoint = a.slice('--set-endpoint='.length);
+    else if (a === '--show-endpoint') opts.showEndpoint = true;
+    else if (a === '--build-next-level') opts.buildNextLevel = true;
+    else if (a === '--force') opts.force = true;
+    // ADR-016: the tier roadmap / "next steps" block is removed from the
+    // default footprint output; `--roadmap` (alias `--next`) shows it again.
+    else if (a === '--roadmap' || a === '--next') opts.roadmap = true;
+    else if (a === '--lang') opts.lang = VALID_LANGS.has(argv[++i]) ? argv[i] : null;
+    else if (a.startsWith('--lang=')) {
+      const value = a.slice('--lang='.length);
+      opts.lang = VALID_LANGS.has(value) ? value : null;
+    }
+    else if (a === '--no-ai') opts.noAi = true;
+    else if (a === '--all-repos') opts.allRepos = true;
+    else if (a === '--machine') opts.machine = true;
+    else if (a === '--repo') opts.repo = true;
+    else if (a === '--scope') opts.scope = parseScope(argv[++i]);
+    else if (a.startsWith('--scope=')) opts.scope = parseScope(a.slice('--scope='.length));
+    else if (a === '--repos') opts.repos = parseRepoList(argv[++i]);
+    else if (a.startsWith('--repos=')) opts.repos = parseRepoList(a.slice('--repos='.length));
+    else if (a === '--help' || a === '-h') opts.help = true;
+  }
+  return opts;
+}
+
+module.exports = { parseArgs };

package/src/command-audit.js

@@ -0,0 +1,105 @@
+'use strict';
+
+const os = require('os');
+const path = require('path');
+const { scrubSecrets } = require('./agent-synthesis');
+const { loadAuthSession } = require('./auth-session-store');
+const { getCertsBase } = require('./config');
+const { postJsonWithTimeout } = require('./backend-request');
+
+// Fire-and-forget: short timeout, every error swallowed, so a logging failure never blocks or fails a command.
+const AUDIT_TIMEOUT_MS = 1500;
+
+// Capped at 200 chars AFTER scrubbing (mirrors MAX_COMMAND_LEN in session-scan.js) so a secret straddling the cut cannot leak.
+const MAX_ARGS_LEN = 200;
+
+function cliVersion() {
+  try {
+    return require(path.join(__dirname, '..', 'package.json')).version || null;
+  } catch {
+    return null;
+  }
+}
+
+// Scrub THEN cap: scrubSecrets can GROW text, so the cap is measured on the scrubbed string that goes on the wire.
+function redactArgs(argv) {
+  if (!Array.isArray(argv) || argv.length === 0) return null;
+  const scrubbed = scrubSecrets(argv.join(' ')).trim().slice(0, MAX_ARGS_LEN);
+  return scrubbed || null;
+}
+
+// Anonymous runs carry only a best-effort machine hint; authenticated runs identify via the Bearer instead.
+function machineHint() {
+  let osUser = null;
+  try {
+    const info = os.userInfo();
+    osUser = info && typeof info.username === 'string' ? info.username : null;
+  } catch {
+    osUser = null;
+  }
+  let hostname = null;
+  try {
+    hostname = os.hostname() || null;
+  } catch {
+    hostname = null;
+  }
+  return { osUser, hostname };
+}
+
+// Builds the record + headers; returns null when there is no endpoint to post to.
+function buildAudit(command, argv, env) {
+  let base;
+  try {
+    base = getCertsBase(env);
+  } catch {
+    base = null;
+  }
+  if (!base) return null;
+
+  const session = loadAuthSession(env);
+  const token =
+    session && (session.accessToken || session.hubAccessToken)
+      ? session.accessToken || session.hubAccessToken
+      : null;
+
+  const body = {
+    command: String(command || 'unknown').slice(0, 100),
+    args: redactArgs(argv),
+    cliVersion: cliVersion(),
+    clientTimestamp: new Date().toISOString(),
+  };
+
+  // Machine hint only when anonymous; identity comes from the token otherwise.
+  if (!token) {
+    const { osUser, hostname } = machineHint();
+    body.osUser = osUser;
+    body.hostname = hostname;
+  }
+
+  const headers = token ? { Authorization: `Bearer ${token}` } : null;
+  const endpoint = `${base.replace(/\/+$/, '')}/cli/command-log`;
+  return { endpoint, body, headers };
+}
+
+// Emits ONE fire-and-forget audit record; never throws or rejects. Returns the `.catch`-guarded promise so tests can await it (production does not).
+function emitCommandAudit({ command, argv = [], env = process.env } = {}) {
+  try {
+    const audit = buildAudit(command, argv, env);
+    if (!audit) return Promise.resolve();
+    return postJsonWithTimeout(
+      audit.endpoint,
+      audit.body,
+      AUDIT_TIMEOUT_MS,
+      'POST',
+      null,
+      audit.headers,
+    ).then(
+      () => {},
+      () => {},
+    );
+  } catch {
+    return Promise.resolve();
+  }
+}
+
+module.exports = { emitCommandAudit, redactArgs, buildAudit };

package/src/config-dir.js

@@ -0,0 +1,120 @@
+'use strict';
+
+const path = require('path');
+const fs = require('fs');
+const { getHomeDir, readEnv } = require('./env-paths');
+
+// Single source of truth for the CLI's config directory (ADR-045).
+
+const DIR_NAME = 'shakers';
+const LEGACY_DIR_NAME = 'ai-footprint';
+
+// Only config.json holds persisted endpoint URLs that must follow the endpoint
+// rename; every other file is copied byte-for-byte.
+const CONFIG_FILE = 'config.json';
+
+// One-time marker dropped in the NEW dir once migration has run.
+const MIGRATION_MARKER = '.migrated-from-ai-footprint';
+
+function overrideDir(env) {
+  return readEnv(env, 'CONFIG_DIR') || null;
+}
+
+function defaultConfigDir(env) {
+  return path.join(getHomeDir(env), '.config', DIR_NAME);
+}
+
+function legacyConfigDir(env) {
+  return path.join(getHomeDir(env), '.config', LEGACY_DIR_NAME);
+}
+
+function getConfigDir(env = process.env) {
+  return overrideDir(env) || defaultConfigDir(env);
+}
+
+// Rewrites the endpoint rename inside any persisted string value.
+function rewriteConfigEndpoints(text) {
+  let parsed;
+  try {
+    parsed = JSON.parse(text);
+  } catch {
+    return text;
+  }
+  const walk = (v) => {
+    if (typeof v === 'string') return v.includes('ai-footprint') ? v.split('ai-footprint').join('usage') : v;
+    if (Array.isArray(v)) return v.map(walk);
+    if (v && typeof v === 'object') {
+      const out = {};
+      for (const k of Object.keys(v)) out[k] = walk(v[k]);
+      return out;
+    }
+    return v;
+  };
+  return `${JSON.stringify(walk(parsed), null, 2)}\n`;
+}
+
+// Atomic write preserving `mode`: temp-in-same-dir + fsync + rename.
+function writeFilePreservingMode(dest, buf, mode, overwrite) {
+  if (!overwrite && fs.existsSync(dest)) return false;
+  const dir = path.dirname(dest);
+  const tmp = path.join(dir, `.${path.basename(dest)}.${process.pid}.${Date.now()}.tmp`);
+  const fd = fs.openSync(tmp, 'wx', mode);
+  try {
+    fs.writeSync(fd, buf);
+    fs.fsyncSync(fd);
+  } finally {
+    fs.closeSync(fd);
+  }
+  fs.renameSync(tmp, dest); // atomic replace within the same directory
+  return true;
+}
+
+// Migrates the legacy config dir to the new one exactly once (guarded by MIGRATION_MARKER).
+function migrateLegacyConfigDir(env = process.env) {
+  // Explicit override: the caller chose the location, nothing to migrate.
+  if (overrideDir(env)) return { migrated: false, reason: 'override' };
+
+  const to = defaultConfigDir(env);
+  const from = legacyConfigDir(env);
+  const marker = path.join(to, MIGRATION_MARKER);
+  try {
+    if (fs.existsSync(marker)) return { migrated: false, reason: 'already-migrated', to };
+    if (!fs.existsSync(from) || !fs.statSync(from).isDirectory()) {
+      return { migrated: false, reason: 'no-legacy', from, to };
+    }
+    fs.mkdirSync(to, { recursive: true });
+    const brought = [];
+    for (const name of fs.readdirSync(from)) {
+      if (name === MIGRATION_MARKER) continue;
+      const src = path.join(from, name);
+      let st;
+      try {
+        st = fs.statSync(src);
+      } catch {
+        continue;
+      }
+      if (!st.isFile()) continue; // the config dir is flat; skip anything odd
+      const dest = path.join(to, name);
+      const isConfig = name === CONFIG_FILE;
+      const buf = isConfig
+        ? Buffer.from(rewriteConfigEndpoints(fs.readFileSync(src, 'utf8')), 'utf8')
+        : fs.readFileSync(src);
+      // config.json overwrites install's default; everything else is copy-if-missing.
+      if (writeFilePreservingMode(dest, buf, st.mode & 0o777, isConfig)) brought.push(name);
+    }
+    // Strictly once: drop the marker so a later boot never re-runs (and never
+    // re-overwrites a config the Talent has since edited in the new dir).
+    fs.writeFileSync(marker, `${new Date().toISOString()}\n`);
+    return { migrated: true, from, to, brought };
+  } catch (err) {
+    return { migrated: false, reason: 'error', error: err && err.message, from, to };
+  }
+}
+
+module.exports = {
+  getConfigDir,
+  legacyConfigDir,
+  defaultConfigDir,
+  migrateLegacyConfigDir,
+  rewriteConfigEndpoints,
+};